@timeback/powerpath 0.2.1 → 0.2.2-beta.20260331190459

package/dist/index.d.ts

@@ -1,1177 +1,1522 @@
-import * as _timeback_internal_client_infra from '@timeback/internal-client-infra';
-import { PowerPathPaths, RequestOptions, PaginatedResponse, ClientConfig, TransportOnlyConfig, ProviderClientConfig, BaseTransportConfig, Paginator as Paginator$1, ListParams, ProviderRegistry, TimebackProvider, AuthCheckResult, BaseTransport } from '@timeback/internal-client-infra';
-export { AuthCheckResult, EnvAuth, Environment, ExplicitAuth, ListParams, PageResult } from '@timeback/internal-client-infra';
+import { ExternalTestCreateResponse, InternalTestCreateResponse, CreateAttemptResponse, FinalizeAssessmentResponse, GetAssessmentProgressResponse, GetAttemptsResponse, GetNextQuestionResponse, ImportExternalResultsResponse, MakeExternalTestAssignmentResponse, ResetAttemptResponse, TestOutResponse, UpdateStudentQuestionResponseResult, LessonPlanCreateResponse, LessonPlanResponse, LessonPlanOperationsResponse, LessonPlanOperationResult, LessonPlanSyncResult, LessonPlanCourseSyncResult, CourseProgressResponse, UpdateStudentItemResponseResult, GetAllPlacementTestsResponse, GetCurrentLevelResponse, GetNextPlacementTestResponse, GetSubjectProgressResponse, ResetPlacementResponse, RenderConfigUpsertResponse, RenderConfigGetResponse, RenderConfigDeleteResponse, ScreeningResultsResponse, ScreeningSessionResponse, ScreeningResetSessionResponse, ScreeningAssignTestResponse, SyllabusResponse, TestAssignment, TestAssignmentsListResponse, AssignmentResult, BulkResult, GetTestOutEligibilityResponse, MakeExternalStudentTestOutAssignmentResponse } from '@timeback/types/protocols/powerpath';
+export { AssignmentResult, Attempt, BulkResult, CourseProgressResponse, CreateAttemptResponse, ExternalTestCapableLessonType, ExternalTestCreateResponse, FinalizeAssessmentResponse, GetAllPlacementTestsResponse, GetAssessmentProgressResponse, GetAttemptsResponse, GetCurrentLevelResponse, GetNextPlacementTestResponse, GetNextQuestionResponse, GetSubjectProgressResponse, GetTestOutEligibilityResponse, ImportExternalResultsResponse, InternalTestCreateResponse, LessonPlanCourseSyncResult, LessonPlanCreateResponse, LessonPlanOperation, LessonPlanOperationResult, LessonPlanOperationsResponse, LessonPlanResponse, LessonPlanSyncResult, MakeExternalStudentTestOutAssignmentResponse, MakeExternalTestAssignmentResponse, PaginationMeta, PowerPath100ProgressResponse, PowerPath100UpdateResponseResult, PowerPathLessonType, PowerPathQuestionContent, PowerPathQuestionDifficulty, PowerPathQuestionResult, PowerPathTestQuestion, QuizLikeLessonType, ResetAttemptResponse, ResetPlacementResponse, ResponseResult, ResponseResultFeedback, ScoreStatus, ScreeningAssignTestResponse, ScreeningResetSessionResponse, ScreeningResultsResponse, ScreeningSessionResponse, StandardProgressResponse, StandardUpdateResponseResult, SyllabusResponse, TestAssignment, TestAssignmentStatus, TestAssignmentsListResponse, TestOutResponse, UpdateStudentItemResponseResult, UpdateStudentQuestionResponseResult } from '@timeback/types/protocols/powerpath';
+import { CreateExternalPlacementTestInput, CreateExternalTestOutInput, CreateInternalTestInput, CreateNewAttemptInput, FinalStudentAssessmentResponseInput, GetAssessmentProgressParams, GetAttemptsParams, GetNextQuestionParams, ImportExternalTestAssignmentResultsParams, MakeExternalTestAssignmentInput, ResetAttemptInput, TestOutParams, UpdateStudentQuestionResponseInput, LessonPlansCreateInput, LessonPlanOperationsInput, LessonPlanUpdateStudentItemResponseInput, PlacementQueryParams, PlacementResetUserPlacementInput, RenderConfigUpsertInput, ScreeningResetSessionInput, ScreeningAssignTestInput, SyllabusQueryParams, TestAssignmentsListParams, TestAssignmentsCreateInput, TestAssignmentsUpdateInput, TestAssignmentsAdminParams, TestAssignmentsBulkInput, TestAssignmentsImportInput, MakeExternalStudentTestOutAssignmentInput } from '@timeback/types/zod';
+export { CreateExternalPlacementTestInput, CreateExternalTestOutInput, CreateInternalTestInput, CreateNewAttemptInput, FinalStudentAssessmentResponseInput, GetAssessmentProgressParams, GetAttemptsParams, GetNextQuestionParams, ImportExternalTestAssignmentResultsParams, LessonPlanOperationInput, LessonPlanOperationsInput, LessonPlanUpdateStudentItemResponseInput, LessonPlansCreateInput, MakeExternalStudentTestOutAssignmentInput, MakeExternalTestAssignmentInput, PlacementQueryParams, PlacementResetUserPlacementInput, ResetAttemptInput, ScreeningAssignTestInput, ScreeningResetSessionInput, SyllabusQueryParams, TestAssignmentsAdminParams, TestAssignmentsBulkInput, TestAssignmentsCreateInput, TestAssignmentsImportInput, TestAssignmentsListParams, TestAssignmentsUpdateInput, TestOutParams, UpdateStudentQuestionResponseInput } from '@timeback/types/zod';
 
 /**
- * PowerPath Base Types
+ * Interface for obtaining OAuth2 access tokens.
  *
- * Common types and enums for PowerPath API responses.
+ * Implementations handle token caching and refresh automatically.
  */
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// ENUMS
-// ═══════════════════════════════════════════════════════════════════════════════
+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;
+}
 
 /**
- * Test assignment status values.
+ * All supported platforms.
  */
-type TestAssignmentStatus =
-	| 'assigned'
-	| 'in_progress'
-	| 'completed'
-	| 'failed'
-	| 'expired'
-	| 'cancelled'
+declare const PLATFORMS: readonly ["BEYOND_AI", "LEARNWITH_AI"];
 
 /**
- * Lesson types for PowerPath assessments.
+ * Type Definitions for `@timeback/internal-logger`
+ *
+ * Central type definitions used across all logger components.
+ * These types define the contract between the logger, formatters, and consumers.
  */
-type PowerPathLessonType =
-	| 'powerpath-100'
-	| 'quiz'
-	| 'test-out'
-	| 'placement'
-	| 'unit-test'
-	| 'alpha-read-article'
-
 /**
- * Lesson types that behave like quizzes (static tests with finalization).
+ * Log severity levels, ordered from least to most severe.
  *
- * These types can be finalized via `finalStudentAssessmentResponse`,
- * return score 0 while not finalized, and support both internal and external tests.
+ * - 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 QuizLikeLessonType = 'quiz' | 'test-out' | 'placement' | 'unit-test'
-
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 /**
- * Lesson types that support external test assignment via third-party tools.
+ * Runtime environments that determine how logs are formatted.
  *
- * These types can use `makeExternalTestAssignment` and
- * `importExternalTestAssignmentResults`.
+ * - 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 ExternalTestCapableLessonType = 'test-out' | 'placement' | 'unit-test'
-
+type Environment$2 = 'terminal' | 'ci' | 'production' | 'browser' | 'test';
 /**
- * Score status values for assessment attempts.
+ * 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 ScoreStatus =
-	| 'exempt'
-	| 'fully graded'
-	| 'not submitted'
-	| 'partially graded'
-	| 'submitted'
-
+type LogContext = Record<string, unknown>;
 /**
- * Question difficulty levels.
+ * Configuration options for creating a logger instance.
  */
-type PowerPathQuestionDifficulty = 'easy' | 'medium' | 'hard'
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// PAGINATION
-// ═══════════════════════════════════════════════════════════════════════════════
+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;
+}
 
 /**
- * Pagination metadata from PowerPath list responses.
- */
-interface PaginationMeta {
-	/** Total items across all pages */
-	totalCount: number
-	/** Total number of pages */
-	pageCount: number
-	/** Current page number (1-indexed) */
-	pageNumber: number
-	/**
-	 * Offset for the next page of results.
-	 *
-	 * This API uses offset pagination: request `offset` is the number of items to skip.
-	 * List responses also include an `offset` field; treat it as the server-provided
-	 * next offset (and fall back to `currentOffset + limit` when implementing iterators).
-	 */
-	offset: number
-	/** Items per page (default 100, max 3000) */
-	limit: number
+ * Logger instance with environment-aware formatting.
+ *
+ * Instances are lightweight and can be created freely.
+ * Common pattern: one logger per module/component.
+ */
+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;
 }
 
 /**
- * PowerPath Response Types
+ * Where Clause Types
  *
- * Entity types returned by PowerPath API endpoints.
+ * Type-safe object syntax for building filter expressions.
  */
-
-
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// TEST ASSIGNMENTS
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
- * A single test assignment entity.
- */
-interface TestAssignment {
-	sourcedId: string
-	studentSourcedId: string
-	studentEmail: string
-	assignedByUserSourcedId: string | null
-	subject: string
-	grade: string
-	assignmentStatus: TestAssignmentStatus
-	testName?: string | null
-	assignedAt?: string | null
-	expiresAt?: string | null
-	completedAt?: string | null
-	resourceSourcedId?: string | null
-	componentResourceSourcedId?: string | null
-}
-
+ * Primitive value types that can be used in filters.
+ */
+type FilterValue = string | number | boolean | Date;
 /**
- * List response for test assignments.
+ * Operators for a single field.
+ *
+ * @example
+ * ```typescript
+ * { status: { ne: 'deleted' } }
+ * { score: { gt: 90 } }
+ * { email: { contains: '@school.edu' } }
+ * { role: { in: ['teacher', 'aide'] } }
+ * ```
  */
-interface TestAssignmentsListResponse extends PaginationMeta {
-	testAssignments: TestAssignment[]
+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[];
 }
-
 /**
- * Result from creating a test assignment.
+ * A field condition can be:
+ * - A direct value (implies equality)
+ * - An object with operators
  */
-interface AssignmentResult {
-	assignmentId: string
-	lessonId: string
-	resourceId: string
-}
-
+type FieldCondition<T> = T | FieldOperators<T>;
 /**
- * Result from bulk operations.
+ * Map filter field types to field conditions.
+ *
+ * Each field in F becomes an optional filter condition.
+ *
+ * @typeParam F - Filter fields type (e.g., UserFilterFields)
  */
-interface BulkResult {
-	success: boolean
-	results: AssignmentResult[]
-	errors: Array<{ row: number; message: string }>
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// QUESTIONS
-// ═══════════════════════════════════════════════════════════════════════════════
-
+type FilterFields<F> = {
+    [K in keyof F]?: FieldCondition<F[K] & FilterValue>;
+};
 /**
- * QTI content associated with a question.
+ * OR condition for combining multiple field conditions.
  */
-interface PowerPathQuestionContent {
-	/** The type of the question (e.g., choiceInteraction) */
-	type?: string
-	/** The raw XML question in QTI format */
-	rawXml: string
+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>;
 
 /**
- * Result of evaluating a student's response to a question.
+ * Shared Types
+ *
+ * Common types for API client infrastructure.
  */
-interface PowerPathQuestionResult {
-	/** Score assigned considering the student's response */
-	score: number
-	/** Feedback — plain string from updateStudentQuestionResponse, structured object from progress/next-question responses */
-	feedback: string | { value: string; identifier: string }
-	/** Outcome variables from response processing (values may be strings or numbers) */
-	outcomes?: Record<string, string | number>
-}
 
 /**
- * A question in a PowerPath test.
- *
- * Represents a question with its metadata, optional QTI content,
- * and (when answered) the student's response and result.
- */
-interface PowerPathTestQuestion {
-	/** ID that represents the question in the test */
-	id: string
-	/** Index of the question in the test */
-	index: number
-	/** Title of the question */
-	title: string
-	/** URL of the QTI question */
-	url: string
-	/** Difficulty of the question */
-	difficulty: PowerPathQuestionDifficulty
-	/** Whether the question has been approved by a human */
-	humanApproved?: boolean | null
-	/** QTI content of the question */
-	content?: PowerPathQuestionContent
-	/** Student's response (single value or array) */
-	response?: string | string[]
-	/** Student's responses keyed by response identifier */
-	responses?: Record<string, string | string[]>
-	/** Whether the student's response is correct */
-	correct?: boolean
-	/** Result of evaluating the response */
-	result?: PowerPathQuestionResult
-	/** sourcedId of the AssessmentResult for this question attempt */
-	resultId?: string
-	/** Learning objective IDs associated with the question */
-	learningObjectives?: string[]
+ * 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 EnvAuth$1 {
+    clientId: string;
+    clientSecret: string;
 }
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// ASSESSMENTS
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
- * Result from creating an external test (test-out or placement).
- */
-interface ExternalTestCreateResponse {
-	/** Type of lesson created. */
-	lessonType: PowerPathLessonType
-	/** The sourcedId of the created lesson (ComponentResource). */
-	lessonId: string
-	/** The sourcedId of the component (unit) containing the test. */
-	courseComponentId: string
-	/** The sourcedId of the resource representing the external test. */
-	resourceId: string
-	/** URL to the external test system. */
-	launchUrl?: string
-	/** The tool provider identifier (e.g. 'edulastic', 'mastery-track'). */
-	toolProvider: string
-	/** The ID of the test in the vendor's system. */
-	vendorId?: string
-	/** The courseId to enroll the student in on failure (placement tests). */
-	courseIdOnFail?: string | null
-	/** Grade levels for the resource. */
-	grades?: Array<number | 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;
 }
-
 /**
- * Result from creating an internal test (QTI or assessment-bank).
- */
-interface InternalTestCreateResponse {
-	/** Type of lesson created. */
-	lessonType: PowerPathLessonType
-	/** The internal test type. */
-	testType: 'qti' | 'assessment-bank'
-	/** The sourcedId of the created lesson (ComponentResource). */
-	lessonId: string
-	/** The sourcedId of the component (unit) containing the test. */
-	courseComponentId: string
-	/** The sourcedId of the main resource (parent for assessment-bank). */
-	resourceId: string
-	/** Child resource IDs (only for assessment-bank type). */
-	childResourceIds?: string[]
-	/** The courseId to enroll the student in on failure (placement tests). */
-	courseIdOnFail?: string | null
-	/** Grade levels for the resource. */
-	grades?: Array<number | string>
+ * Base configuration options shared by all modes.
+ */
+interface BaseConfig$1 {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Custom fetch implementation */
+    fetch?: FetchFn$1;
 }
-
 /**
- * A single attempt record.
- *
- * Matches the backend `PowerPath100AttemptSchema` with full metadata
- * including XP, timestamps, and typed score status.
- */
-interface Attempt {
-	/** Attempt number, or null if not yet started. */
-	attempt: number | null
-	/** Current score for this attempt. */
-	score: number
-	/** Grading status of this attempt. */
-	scoreStatus: ScoreStatus
-	/** XP earned in this attempt. */
-	xp: number | null
-	/** When this attempt was started. */
-	startedAt: string | null
-	/** When this attempt was completed. */
-	completedAt: string | null
+ * 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;
 }
-
 /**
- * Result from creating a new attempt.
+ * Environment-based configuration with shared token provider.
  */
-interface CreateAttemptResponse {
-	attempt: Attempt
+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;
 }
-
 /**
- * Result from getting attempts for a lesson.
+ * Explicit URL configuration for custom APIs.
+ * Supports both authenticated and public/no-auth services.
  */
-interface GetAttemptsResponse {
-	attempts: Attempt[]
+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;
 }
-
 /**
- * Result from resetting an attempt.
+ * Use pre-configured transport.
  */
-interface ResetAttemptResponse {
-	success: boolean
-	score: number
+interface TransportConfig extends BaseConfig$1 {
+    /** Transport configuration */
+    transport: TransportLike;
 }
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// ASSESSMENT PROGRESS (getAssessmentProgress)
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
- * Progress for a PowerPath 100 lesson.
- *
- * Uses `seenQuestions` (not `questions`) and includes remaining question counts
- * per difficulty level.
- */
-interface PowerPath100ProgressResponse {
-	lessonType: 'powerpath-100'
-	/** Remaining question counts per difficulty level */
-	remainingQuestionsPerDifficulty: {
-		easy: number
-		medium: number
-		hard: number
-	}
-	/** Current score for this attempt */
-	score: number
-	/** Questions the student has seen */
-	seenQuestions: PowerPathTestQuestion[]
-	/** sourcedId of the parent test AssessmentResult */
-	testResultId?: string
-	/** Attempt number */
-	attempt: number
-	/** XP earned in the lesson */
-	xp: number | null
-	/** Multiplier for XP */
-	multiplier: number | null
-	/** Accuracy of the student's attempted questions */
-	accuracy: number
-	/** Number of correct questions answered */
-	correctQuestions: number
-	/** Total number of questions in the lesson */
-	totalQuestions: number
+ * 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;
 }
-
 /**
- * Progress for quiz, test-out, placement, or unit-test lessons.
- *
- * Uses `questions` (not `seenQuestions`). Includes `finalized` to indicate
- * whether the lesson has been completed.
- */
-interface StandardProgressResponse {
-	lessonType: 'quiz' | 'test-out' | 'placement' | 'unit-test'
-	/** Whether the lesson has been finalized in the current attempt */
-	finalized: boolean
-	/** Current score for this attempt */
-	score?: number
-	/** Questions in the test */
-	questions: PowerPathTestQuestion[]
-	/** Tool provider of the lesson if external */
-	toolProvider: string | null
-	/** Whether auto-enrollment failed (only for finalized external tests) */
-	enrollmentFailed?: boolean
-	/** sourcedId of the parent test AssessmentResult */
-	testResultId?: string
-	/** Attempt number */
-	attempt: number
-	/** XP earned in the lesson */
-	xp: number | null
-	/** Multiplier for XP */
-	multiplier: number | null
-	/** Accuracy of the student's attempted questions */
-	accuracy: number
-	/** Number of correct questions answered */
-	correctQuestions: number
-	/** Total number of questions in the lesson */
-	totalQuestions: number
+ * 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>;
 }
-
 /**
- * Result from getting assessment progress.
+ * Configuration using a pre-configured transport.
  *
- * Discriminated union on `lessonType`:
- * - `'powerpath-100'` — uses `seenQuestions` and `remainingQuestionsPerDifficulty`
- * - `'quiz' | 'test-out' | 'placement' | 'unit-test'` — uses `questions` and `finalized`
+ * For advanced use cases like sharing a transport between clients
+ * or using a custom transport implementation.
+ *
+ * @template T - Transport type (defaults to TransportLike, clients should specify their full transport type)
  */
-type GetAssessmentProgressResponse = PowerPath100ProgressResponse | StandardProgressResponse
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// GET NEXT QUESTION (getNextQuestion)
-// ═══════════════════════════════════════════════════════════════════════════════
-
+interface TransportOnlyConfig<T extends TransportLike = TransportLike> {
+    /** Existing transport instance */
+    transport: T;
+}
 /**
- * Result from getting the next question in a PowerPath 100 lesson.
+ * Union of all client configuration types.
  */
-interface GetNextQuestionResponse {
-	/** Current PowerPath score of the student in this lesson */
-	score: number
-	/** The next question to present */
-	question: PowerPathTestQuestion
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// UPDATE STUDENT QUESTION RESPONSE (updateStudentQuestionResponse)
-// ═══════════════════════════════════════════════════════════════════════════════
-
+type ClientConfig = EnvConfig | TokenProviderEnvConfig | ExplicitConfig | TransportConfig | Partial<ExplicitConfig>;
 /**
- * Response feedback for a student's answer.
+ * 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
+ * // Type-safe where
+ * client.users.list({
+ *   where: { status: 'active', role: 'teacher' },
+ *   sort: 'familyName',
+ * })
+ * ```
  */
-interface ResponseResultFeedback {
-	identifier?: string
-	value?: string
+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;
 }
-
 /**
- * Result of processing a student's response.
+ * Response from a paginated API request.
  */
-interface ResponseResult {
-	/** Whether the student's response is correct */
-	isCorrect: boolean
-	/** Score for this specific response (0 or 1) */
-	score: number
-	/** Optional feedback */
-	feedback?: ResponseResultFeedback
+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;
 }
-
 /**
- * Result from updating a student's response in a PowerPath 100 lesson.
- *
- * Includes the updated PowerPath score, response correctness, and accuracy stats.
- */
-interface PowerPath100UpdateResponseResult {
-	lessonType: 'powerpath-100'
-	/** Updated PowerPath score */
-	powerpathScore: number
-	/** Result of processing the response */
-	responseResult: ResponseResult
-	/** Assessment result for the question (for debugging) */
-	questionResult?: unknown
-	/** Assessment result for the test (for debugging) */
-	testResult?: unknown
-	/** Accuracy of the student's attempted questions */
-	accuracy: number
-	/** Number of correct questions answered */
-	correctQuestions: number
-	/** Total number of questions */
-	totalQuestions: number
-	/** XP earned */
-	xp: number | null
-	/** XP multiplier */
-	multiplier: number | null
+ * 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;
 }
-
 /**
- * Result from updating a student's response in a quiz/test-out/placement/unit-test lesson.
- *
- * Minimal response — correctness is evaluated at finalization.
+ * Options for toArray() method.
  */
-interface StandardUpdateResponseResult {
-	lessonType: 'quiz' | 'test-out' | 'placement' | 'unit-test'
-	/** Assessment result for the question (for debugging) */
-	questionResult?: unknown
+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;
 }
-
 /**
- * Result from updating a student question response.
- *
- * Discriminated union on `lessonType`:
- * - `'powerpath-100'` — includes score, accuracy, and response correctness
- * - Other lesson types — minimal, evaluated at finalization
+ * Function that fetches a page of results.
+ * Provided by the transport layer.
  */
-type UpdateStudentQuestionResponseResult =
-	| PowerPath100UpdateResponseResult
-	| StandardUpdateResponseResult
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// FINALIZE ASSESSMENT (finalStudentAssessmentResponse)
-// ═══════════════════════════════════════════════════════════════════════════════
-
+type PageFetcher<T> = (path: string, options: {
+    params: Record<string, string | number | boolean | undefined>;
+}) => Promise<PaginatedResponse<T>>;
 /**
- * Result from finalizing a test assessment.
+ * Pagination style for API requests.
  *
- * Returned after all questions have been answered and the lesson is
- * evaluated. Only applicable to quiz-like lesson types (quiz, test-out,
- * placement, unit-test). Not applicable to `powerpath-100`.
+ * - `'offset'`: Uses limit/offset parameters (default, e.g., OneRoster)
+ * - `'page'`: Uses limit/page parameters (1-indexed, e.g., QTI)
+ */
+type PaginationStyle = 'offset' | 'page';
+/**
+ * Options for creating a Paginator.
  */
-interface FinalizeAssessmentResponse {
-	/** Type of the lesson that was finalized (quiz-like only). */
-	lessonType: QuizLikeLessonType
-	/** Whether the lesson has been finalized. */
-	finalized: boolean
-	/** The attempt number. */
-	attempt: number
+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;
 }
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// TEST OUT (testOut)
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
- * Result from getting the test-out lesson for a student/course.
- *
- * Returns the test-out lesson reference, finalization status,
- * and optional external tool credentials.
- */
-interface TestOutResponse {
-	lessonType: 'test-out'
-	/** ID of the test-out lesson, or null if none exists */
-	lessonId: string | null
-	/** Whether the test-out has been finalized in the current attempt */
-	finalized: boolean
-	/** Tool provider for the test-out lesson, or null if internal */
-	toolProvider: string | null
-	/** Attempt number */
-	attempt?: number
-	/** Credentials for accessing the assigned test on external tool */
-	credentials?: {
-		email: string
-		password: string
-	}
-	/** Assignment ID on external tool for results retrieval */
-	assignmentId?: string
-	/** Class ID on external tool for results retrieval */
-	classId?: string
-	/** URL of the test on external tool */
-	testUrl?: string
-	/** ID of the test on external tool */
-	testId?: string
+ * 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;
+    };
 }
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// IMPORT EXTERNAL RESULTS (importExternalTestAssignmentResults)
-// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Config Types
+ *
+ * Types for TimebackProvider and provider resolution.
+ */
 
 /**
- * Result from importing external test assignment results.
- *
- * Contains the lesson reference, finalization status, and optional
- * external tool credentials/assignment data.
- */
-interface ImportExternalResultsResponse {
-	/** Lesson type (external-capable types only). */
-	lessonType: ExternalTestCapableLessonType
-	/** The sourcedId of the lesson (ComponentResource). */
-	lessonId: string | null
-	/** The tool provider for the lesson. */
-	toolProvider: string | null
-	/** Whether the test has been finalized in the current attempt. */
-	finalized: boolean
-	/** Attempt number. */
-	attempt: number
-	/** Credentials for accessing the assigned test on external tool. */
-	credentials?: {
-		email: string
-		password: string
-	}
-	/** Assignment ID on external tool for results retrieval. */
-	assignmentId?: string
-	/** Class ID on external tool for results retrieval. */
-	classId?: string
-	/** URL of the test on external tool. */
-	testUrl?: string
-	/** ID of the test on external tool. */
-	testId?: string
+ * 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;
 }
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// MAKE EXTERNAL TEST ASSIGNMENT (makeExternalTestAssignment)
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
- * Result from assigning an external test to a student.
- *
- * Contains the tool provider, lesson type, attempt number, and optional
- * external tool credentials/assignment data.
- */
-interface MakeExternalTestAssignmentResponse {
-	/** The tool provider (e.g. 'edulastic', 'mastery-track'). */
-	toolProvider: string
-	/** Lesson type (external-capable types only). */
-	lessonType: ExternalTestCapableLessonType
-	/** Attempt number. */
-	attempt: number
-	/** Credentials for accessing the assigned test on external tool. */
-	credentials?: {
-		email: string
-		password: string
-	}
-	/** Assignment ID on external tool for results retrieval. */
-	assignmentId?: string
-	/** Class ID on external tool for results retrieval. */
-	classId?: string
-	/** URL of the test on external tool. */
-	testUrl?: string
-	/** ID of the test on external tool. */
-	testId?: string
+ * 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;
 }
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// PLACEMENT
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
- * Result from getting all placement tests.
- */
-interface GetAllPlacementTestsResponse {
-	placementTests: unknown[]
+ * 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;
 }
-
 /**
- * Result from getting current placement level.
+ * OneRoster API path profile.
+ * Defines the base path prefix for all OneRoster resources.
  */
-interface GetCurrentLevelResponse {
-	gradeLevel?: unknown
-	onboarded?: boolean
-	availableTests: number
+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;
 }
-
 /**
- * Result from getting the next placement test.
+ * Edubridge API path profile.
+ * Defines path prefixes for Edubridge operations.
  */
-interface GetNextPlacementTestResponse {
-	availableTests: number
-	lesson: string
+interface EdubridgePaths {
+    /** Base path prefix for all Edubridge resources */
+    base: string;
 }
-
 /**
- * Result from getting subject progress.
+ * PowerPath API path profile.
+ * Defines path prefixes for PowerPath operations.
  */
-interface GetSubjectProgressResponse {
-	progress: unknown[]
+interface PowerPathPaths {
+    /** Base path prefix for all PowerPath resources */
+    base: string;
 }
-
 /**
- * Result from resetting placement.
+ * CASE API path profile.
+ * Defines path prefix for CASE (Competency and Academic Standards Exchange) operations.
  */
-interface ResetPlacementResponse {
-	success: boolean
-	placementResultsDeleted: number
-	onboardingReset: boolean
+interface CasePaths {
+    /** Base path prefix for all CASE resources */
+    base: string;
 }
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// SCREENING
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
- * Result from screening getResults.
- * Response shape depends on MAP integration configuration.
+ * CLR API path profile.
+ * Defines path prefixes for CLR (Comprehensive Learner Record) operations.
  */
-interface ScreeningResultsResponse {
-	[key: string]: unknown
+interface ClrPaths {
+    /** Path for upserting CLR credentials (POST) */
+    credentials: string;
+    /** Path for API discovery (GET) */
+    discovery: string;
 }
-
 /**
- * Result from screening getSession.
- * Response shape depends on MAP integration configuration.
+ * 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.
  */
-interface ScreeningSessionResponse {
-	[key: string]: unknown
+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;
 }
-
 /**
- * Result from resetting a screening session.
+ * Auth credentials for a provider.
  */
-interface ScreeningResetSessionResponse {
-	success?: boolean
-	[key: string]: unknown
+interface ProviderAuth {
+    clientId: string;
+    clientSecret: string;
 }
-
 /**
- * Result from assigning a screening test.
+ * 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 ScreeningAssignTestResponse {
-	success?: boolean
-	[key: string]: unknown
+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>;
 }
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// LESSON PLANS
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
- * Result from creating a lesson plan.
+ * 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.
  */
-interface LessonPlanCreateResponse {
-	lessonPlanId: string
+type TimebackProviderConfig = ProviderEnvConfig | ProviderExplicitConfig | ProviderServicesConfig;
+/**
+ * Provider template - endpoints without auth.
+ * Used internally to define available platform+env combinations.
+ */
+interface ProviderTemplate {
+    platform: Platform;
+    env: Environment;
 }
-
 /**
- * A lesson plan operation record.
+ * Registry of provider templates indexed by platform and environment.
+ *
+ * Use `satisfies ProviderRegistry` when defining a registry for type checking.
+ *
+ * @example
+ * const myRegistry = {
+ *   defaultPlatform: 'MY_PLATFORM',
+ *   templates: {
+ *     MY_PLATFORM: {
+ *       staging: { platform: 'BEYOND_AI', env: 'staging' },
+ *       production: { platform: 'BEYOND_AI', env: 'production' },
+ *     },
+ *   },
+ * } satisfies ProviderRegistry
  */
-interface LessonPlanOperation {
-	id: string
-	type: string
-	payload?: unknown
-	reason?: string
-	createdAt: string
-	sequenceNumber: number
-	createdBy?: string
+interface ProviderRegistry {
+    /** Default platform when none specified */
+    defaultPlatform: string;
+    /** Available templates indexed by platform → env */
+    templates: Record<string, Record<string, ProviderTemplate>>;
 }
-
 /**
- * Response containing lesson plan operations.
+ * Client config that accepts a pre-built provider.
  */
-interface LessonPlanOperationsResponse {
-	operations: LessonPlanOperation[]
+interface ProviderClientConfig {
+    /** Pre-built provider */
+    provider: TimebackProvider;
 }
 
 /**
- * Result from a single lesson plan operation.
+ * Timeback Provider
+ *
+ * Encapsulates platform connection configuration including endpoints and auth.
+ * Providers are complete "connection" objects that clients consume.
  */
-interface LessonPlanOperationResult {
-	success: boolean
-	message?: string
-	operationId?: string
-}
 
 /**
- * Result from syncing lesson plan operations.
+ * 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
+ * // Environment-based provider (Timeback hosted)
+ * const provider = new TimebackProvider({
+ *   platform: 'BEYOND_AI',
+ *   env: 'staging',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Explicit URL provider (self-hosted)
+ * const provider = new TimebackProvider({
+ *   baseUrl: 'https://api.myschool.edu',
+ *   authUrl: 'https://auth.myschool.edu/oauth/token',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 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 LessonPlanSyncResult {
-	success: boolean
-	message?: string
-	operationCount: number
-	operationResults: Array<{ success: boolean; errors?: Array<{ message: string }> }>
+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;
 }
 
 /**
- * Result from syncing a course.
+ * Transport Types
+ *
+ * Types for HTTP transport layer.
  */
-interface LessonPlanCourseSyncResult {
-	lessonPlansAffected: string[]
-}
 
 /**
- * Response containing a lesson plan.
+ * Fetch function signature for HTTP requests.
+ * Avoids Bun-specific extensions on `typeof fetch`.
  */
-interface LessonPlanResponse {
-	lessonPlan: Record<string, unknown>
+type FetchFn = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/**
+ * 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;
 }
-
 /**
- * Response containing course progress.
+ * Auth credentials for environment mode.
+ * Token URL is derived automatically from environment.
  */
-interface CourseProgressResponse {
-	lineItems: Record<string, unknown>[]
+interface EnvAuth {
+    clientId: string;
+    clientSecret: string;
 }
-
 /**
- * Result from updating student item response.
+ * Auth credentials for explicit mode.
+ * Requires explicit authUrl for custom APIs.
  */
-interface UpdateStudentItemResponseResult {
-	success?: boolean
-	[key: string]: unknown
+interface ExplicitAuth {
+    clientId: string;
+    clientSecret: string;
+    authUrl: string;
 }
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// TEST OUT (self-elected)
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
- * Result from checking test-out eligibility for a student/subject.
+ * Base configuration options shared by all modes.
  */
-interface GetTestOutEligibilityResponse {
-	eligible: boolean
-	reason?: string
+interface BaseConfig {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Custom fetch implementation */
+    fetch?: FetchFn;
 }
-
 /**
- * Result from creating a self-elected test-out assignment.
+ * Internal resolved transport configuration.
  */
-interface MakeExternalStudentTestOutAssignmentResponse {
-	success: boolean
-	data?: Record<string, unknown>
+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;
 }
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// RENDER CONFIG
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
- * Result from upserting render configs for one or more courses.
+ * Transport configuration with explicit auth.
  */
-interface RenderConfigUpsertResponse {
-	updated: string[]
+interface TransportConfigWithAuth extends BaseConfig {
+    baseUrl: string;
+    auth: ExplicitAuth;
+    tokenProvider?: never;
 }
-
 /**
- * Render config for a single course.
+ * Transport configuration with shared token provider.
  */
-interface RenderConfigGetResponse {
-	courseId: string
-	rendererId: string
-	rendererUrl: string
-	rendererVersion?: string | null
-	suppressFeedback: boolean
-	suppressCorrectResponse: boolean
+interface TransportConfigWithTokenProvider extends BaseConfig {
+    baseUrl: string;
+    tokenProvider: TokenProvider;
+    auth?: never;
 }
-
 /**
- * Result from deleting a render config.
+ * Transport configuration for public/no-auth services.
  */
-interface RenderConfigDeleteResponse {
-	deleted: string
+interface TransportConfigNoAuth extends BaseConfig {
+    baseUrl: string;
+    auth?: never;
+    tokenProvider?: never;
 }
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// SYLLABUS
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
- * Response containing syllabus data.
+ * Configuration for BaseTransport.
+ */
+type BaseTransportConfig = TransportConfigWithAuth | TransportConfigWithTokenProvider | TransportConfigNoAuth;
+/**
+ * Options for creating a BaseTransport.
  */
-interface SyllabusResponse {
-	syllabus?: unknown
+interface BaseTransportOptions {
+    /** Transport configuration */
+    config: BaseTransportConfig;
+    /** Logger instance for request/response logging */
+    logger: Logger;
 }
-
-type input<T> = T extends {
-    _zod: {
-        input: any;
+/**
+ * Result of an auth check operation.
+ */
+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;
     };
-} ? T["_zod"]["input"] : unknown;
+}
 
 /**
- * PowerPath Schemas
+ * Base Transport Layer
+ *
+ * HTTP transport with OAuth2 authentication, retries, and error handling.
+ * Clients can extend this for protocol-specific features.
  *
- * Zod schemas for the PowerPath adaptive learning API.
  */
+/**
+ * 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;
+}
 
+/**
+ * Pagination Utilities
+ *
+ * Helpers for iterating over paginated API responses.
+ */
 
-
-declare const ExternalTestOut = ExternalTestBase.extend({
-	lessonType: z.literal('test-out'),
-	xp: z.number(),
-})
-
-declare const ExternalPlacement = ExternalTestBase.extend({
-	lessonType: z.literal('placement'),
-	courseIdOnFail: NonEmptyString.nullable().optional(),
-	xp: z.number().optional(),
-})
-
-declare const PowerPathCreateExternalPlacementTestInput = ExternalPlacement
-
-declare const PowerPathCreateExternalTestOutInput = ExternalTestOut
-
-declare const PowerPathCreateInternalTestInput = z.discriminatedUnion('testType', [
-	InternalTestBase.extend({
-		testType: z.literal('qti'),
-		qti: z.object({
-			url: z.url(),
-			title: NonEmptyString.optional(),
-			metadata: z.record(z.string(), z.unknown()).optional(),
-		}),
-	}),
-	InternalTestBase.extend({
-		testType: z.literal('assessment-bank'),
-		assessmentBank: z.object({
-			resources: z
-				.array(
-					z.object({
-						url: z.url(),
-						title: NonEmptyString.optional(),
-						metadata: z.record(z.string(), z.unknown()).optional(),
-					}),
-				)
-				.min(1),
-		}),
-	}),
-])
-
-declare const PowerPathCreateNewAttemptInput = z.object({
-	student: NonEmptyString,
-	lesson: NonEmptyString,
-})
-
-declare const PowerPathFinalStudentAssessmentResponseInput = z.object({
-	student: NonEmptyString,
-	lesson: NonEmptyString,
-})
-
-declare const PowerPathLessonPlansCreateInput = z.object({
-	courseId: NonEmptyString,
-	userId: NonEmptyString,
-	classId: NonEmptyString.optional(),
-})
-
-declare const PowerPathLessonPlanOperationInput = z.union([
-	z.object({
-		type: z.literal('set-skipped'),
-		payload: z.object({
-			target: LessonPlanTarget,
-			value: z.boolean(),
-		}),
-	}),
-	z.object({
-		type: z.literal('add-custom-resource'),
-		payload: z.object({
-			resource_id: NonEmptyString,
-			parent_component_id: NonEmptyString,
-			skipped: z.boolean().optional(),
-		}),
-	}),
-	z.object({
-		type: z.literal('move-item-before'),
-		payload: z.object({
-			target: LessonPlanTarget,
-			reference_id: NonEmptyString,
-		}),
-	}),
-	z.object({
-		type: z.literal('move-item-after'),
-		payload: z.object({
-			target: LessonPlanTarget,
-			reference_id: NonEmptyString,
-		}),
-	}),
-	z.object({
-		type: z.literal('move-item-to-start'),
-		payload: z.object({
-			target: LessonPlanTarget,
-		}),
-	}),
-	z.object({
-		type: z.literal('move-item-to-end'),
-		payload: z.object({
-			target: LessonPlanTarget,
-		}),
-	}),
-	z.object({
-		type: z.literal('change-item-parent'),
-		payload: z.object({
-			target: LessonPlanTarget,
-			new_parent_id: NonEmptyString,
-			position: z.enum(['start', 'end']).optional(),
-		}),
-	}),
-])
-
-declare const PowerPathLessonPlanOperationsInput = z.object({
-	operation: PowerPathLessonPlanOperationInput,
-	reason: NonEmptyString.optional(),
-})
-
-declare const PowerPathLessonPlanUpdateStudentItemResponseInput = z.object({
-	studentId: NonEmptyString,
-	componentResourceId: NonEmptyString,
-	result: z.object({
-		status: z.enum(['active', 'tobedeleted']),
-		metadata: z.record(z.string(), z.unknown()).optional(),
-		score: z.number().optional(),
-		textScore: NonEmptyString.optional(),
-		scoreDate: z.string().datetime(),
-		scorePercentile: z.number().optional(),
-		scoreStatus: ScoreStatus,
-		comment: NonEmptyString.optional(),
-		learningObjectiveSet: z
-			.array(
-				z.object({
-					source: NonEmptyString,
-					learningObjectiveResults: z.array(
-						z.object({
-							learningObjectiveId: NonEmptyString,
-							score: z.number().optional(),
-							textScore: NonEmptyString.optional(),
-						}),
-					),
-				}),
-			)
-			.optional(),
-		inProgress: NonEmptyString.optional(),
-		incomplete: NonEmptyString.optional(),
-		late: NonEmptyString.optional(),
-		missing: NonEmptyString.optional(),
-	}),
-})
-
-declare const PowerPathMakeExternalTestAssignmentInput = z.object({
-	student: NonEmptyString,
-	lesson: NonEmptyString,
-	applicationName: NonEmptyString.optional(),
-	testId: NonEmptyString.optional(),
-	skipCourseEnrollment: z.boolean().optional(),
-})
-
-declare const PowerPathPlacementResetUserPlacementInput = z.object({
-	student: NonEmptyString,
-	subject: TimebackSubject,
-})
-
-declare const PowerPathResetAttemptInput = z.object({
-	student: NonEmptyString,
-	lesson: NonEmptyString,
-})
-
-declare const PowerPathScreeningResetSessionInput = z.object({
-	userId: NonEmptyString,
-})
-
-declare const PowerPathScreeningAssignTestInput = z.object({
-	userId: NonEmptyString,
-	subject: z.enum(['Math', 'Reading', 'Language', 'Science']),
-})
-
-declare const PowerPathTestAssignmentsCreateInput = z.object({
-	student: NonEmptyString,
-	subject: TimebackSubject,
-	grade: TimebackGrade,
-	testName: NonEmptyString.optional(),
-})
-
-declare const PowerPathTestAssignmentsUpdateInput = z.object({
-	testName: NonEmptyString,
-})
-
-declare const PowerPathTestAssignmentsBulkInput = z.object({
-	items: z.array(PowerPathTestAssignmentItemInput),
-})
-
-declare const PowerPathTestAssignmentsImportInput = z.object({
-	spreadsheetUrl: z.url(),
-	sheet: NonEmptyString,
-})
-
-declare const PowerPathTestAssignmentsListParams = z.object({
-	student: NonEmptyString,
-	status: z
-		.enum(['assigned', 'in_progress', 'completed', 'failed', 'expired', 'cancelled'])
-		.optional(),
-	subject: NonEmptyString.optional(),
-	grade: TimebackGrade.optional(),
-	limit: z.number().int().positive().max(3000).optional(),
-	offset: z.number().int().nonnegative().optional(),
-})
-
-declare const PowerPathTestAssignmentsAdminParams = z.object({
-	student: NonEmptyString.optional(),
-	status: z
-		.enum(['assigned', 'in_progress', 'completed', 'failed', 'expired', 'cancelled'])
-		.optional(),
-	subject: NonEmptyString.optional(),
-	grade: TimebackGrade.optional(),
-	limit: z.number().int().positive().max(3000).optional(),
-	offset: z.number().int().nonnegative().optional(),
-})
-
-declare const PowerPathUpdateStudentQuestionResponseInput = z
-	.object({
-		student: NonEmptyString,
-		question: NonEmptyString,
-		response: z.union([NonEmptyString, z.array(NonEmptyString)]).optional(),
-		responses: z
-			.record(z.string(), z.union([NonEmptyString, z.array(NonEmptyString)]))
-			.optional(),
-		lesson: NonEmptyString,
-		rendererOutcomes: z
-			.object({
-				score: z.number(),
-				maxScore: z.number().min(0),
-				isCorrect: z.boolean(),
-			})
-			.optional(),
-		playerState: z.string().optional(),
-	})
-	.refine(data => data.response !== undefined || data.responses !== undefined, {
-		message: "Either 'response' or 'responses' must be provided",
-		path: ['response', 'responses'],
-	})
-	.transform(data => {
-		if (data.response !== undefined && data.responses === undefined) {
-			return { ...data, responses: { RESPONSE: data.response } }
-		}
-
-		return data
-	})
-
-declare const PowerPathGetAssessmentProgressParams = z.object({
-	student: NonEmptyString,
-	lesson: NonEmptyString,
-	attempt: z.number().int().positive().optional(),
-})
-
-declare const PowerPathGetNextQuestionParams = z.object({
-	student: NonEmptyString,
-	lesson: NonEmptyString,
-})
-
-declare const PowerPathGetAttemptsParams = z.object({
-	student: NonEmptyString,
-	lesson: NonEmptyString,
-})
-
-declare const PowerPathTestOutParams = z.object({
-	student: NonEmptyString,
-	course: NonEmptyString,
-})
-
-declare const PowerPathImportExternalTestAssignmentResultsParams = z.object({
-	student: NonEmptyString,
-	lesson: NonEmptyString,
-	applicationName: NonEmptyString.optional(),
-})
-
-declare const PowerPathPlacementQueryParams = z.object({
-	student: NonEmptyString,
-	subject: TimebackSubject,
-})
-
-declare const PowerPathMakeExternalStudentTestOutAssignmentInput = z.object({
-	oneRosterSourcedId: NonEmptyString,
-	subject: NonEmptyString,
-})
-
-declare const PowerPathRenderConfigUpsertInput = z.object({
-	courseIds: z.array(NonEmptyString).min(1),
-	rendererId: NonEmptyString,
-	rendererUrl: z.url(),
-	rendererVersion: NonEmptyString.optional(),
-	suppressFeedback: z.boolean().optional(),
-	suppressCorrectResponse: z.boolean().optional(),
-})
-
-declare const PowerPathSyllabusQueryParams = z.object({
-	status: z.enum(['active', 'tobedeleted']).optional(),
-})
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// TYPE EXPORTS (REQUEST INPUTS)
-// ═══════════════════════════════════════════════════════════════════════════════
-
-// Shorter type aliases (like OneRoster pattern: schema = OneRosterFoo, type = Foo)
-type CreateExternalPlacementTestInput = input<
-	typeof PowerPathCreateExternalPlacementTestInput
->
-type CreateExternalTestOutInput = input<typeof PowerPathCreateExternalTestOutInput>
-type CreateInternalTestInput = input<typeof PowerPathCreateInternalTestInput>
-type CreateNewAttemptInput = input<typeof PowerPathCreateNewAttemptInput>
-type FinalStudentAssessmentResponseInput = input<
-	typeof PowerPathFinalStudentAssessmentResponseInput
->
-type LessonPlansCreateInput = input<typeof PowerPathLessonPlansCreateInput>
-type LessonPlanOperationInput = input<typeof PowerPathLessonPlanOperationInput>
-type LessonPlanOperationsInput = input<typeof PowerPathLessonPlanOperationsInput>
-type LessonPlanUpdateStudentItemResponseInput = input<
-	typeof PowerPathLessonPlanUpdateStudentItemResponseInput
->
-type MakeExternalTestAssignmentInput = input<
-	typeof PowerPathMakeExternalTestAssignmentInput
->
-type PlacementResetUserPlacementInput = input<
-	typeof PowerPathPlacementResetUserPlacementInput
->
-type ResetAttemptInput = input<typeof PowerPathResetAttemptInput>
-type ScreeningResetSessionInput = input<typeof PowerPathScreeningResetSessionInput>
-type ScreeningAssignTestInput = input<typeof PowerPathScreeningAssignTestInput>
-type TestAssignmentsCreateInput = input<typeof PowerPathTestAssignmentsCreateInput>
-type TestAssignmentsUpdateInput = input<typeof PowerPathTestAssignmentsUpdateInput>
-type TestAssignmentsBulkInput = input<typeof PowerPathTestAssignmentsBulkInput>
-type TestAssignmentsImportInput = input<typeof PowerPathTestAssignmentsImportInput>
-type TestAssignmentsListParams = input<typeof PowerPathTestAssignmentsListParams>
-type TestAssignmentsAdminParams = input<typeof PowerPathTestAssignmentsAdminParams>
-type UpdateStudentQuestionResponseInput = input<
-	typeof PowerPathUpdateStudentQuestionResponseInput
->
-type GetAssessmentProgressParams = input<typeof PowerPathGetAssessmentProgressParams>
-type GetNextQuestionParams = input<typeof PowerPathGetNextQuestionParams>
-type GetAttemptsParams = input<typeof PowerPathGetAttemptsParams>
-type TestOutParams = input<typeof PowerPathTestOutParams>
-type ImportExternalTestAssignmentResultsParams = input<
-	typeof PowerPathImportExternalTestAssignmentResultsParams
->
-type MakeExternalStudentTestOutAssignmentInput = input<
-	typeof PowerPathMakeExternalStudentTestOutAssignmentInput
->
-type PlacementQueryParams = input<typeof PowerPathPlacementQueryParams>
-type RenderConfigUpsertInput = input<typeof PowerPathRenderConfigUpsertInput>
-type SyllabusQueryParams = input<typeof PowerPathSyllabusQueryParams>
+/**
+ * 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`)
+ * ```
+ */
+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>>;
+}
 
 /**
  * Transport interface for PowerPath client.
@@ -1525,7 +1870,7 @@ declare class TestOutResource {
 declare const PowerPathClient: {
     new (config?: PowerPathClientConfig): {
         readonly transport: PowerPathTransportLike;
-        readonly _provider?: _timeback_internal_client_infra.TimebackProvider | undefined;
+        readonly _provider?: TimebackProvider | undefined;
         readonly assessments: AssessmentResource;
         readonly lessonPlans: LessonPlansResource;
         readonly placement: PlacementResource;
@@ -1535,7 +1880,7 @@ declare const PowerPathClient: {
         readonly testAssignments: TestAssignmentsResource;
         readonly testOut: TestOutResource;
         getTransport(): PowerPathTransportLike;
-        checkAuth(): Promise<_timeback_internal_client_infra.AuthCheckResult>;
+        checkAuth(): Promise<AuthCheckResult>;
     };
 };
 
@@ -1622,4 +1967,4 @@ declare class Transport extends BaseTransport {
 }
 
 export { Paginator, PowerPathClient, Transport, createPowerPathClient };
-export type { AssignmentResult, Attempt, BulkResult, CourseProgressResponse, CreateAttemptResponse, CreateExternalPlacementTestInput, CreateExternalTestOutInput, CreateInternalTestInput, CreateNewAttemptInput, ExternalTestCapableLessonType, ExternalTestCreateResponse, FinalStudentAssessmentResponseInput, FinalizeAssessmentResponse, GetAllPlacementTestsResponse, GetAssessmentProgressParams, GetAssessmentProgressResponse, GetAttemptsParams, GetAttemptsResponse, GetCurrentLevelResponse, GetNextPlacementTestResponse, GetNextQuestionParams, GetNextQuestionResponse, GetSubjectProgressResponse, GetTestOutEligibilityResponse, ImportExternalResultsResponse, ImportExternalTestAssignmentResultsParams, InternalTestCreateResponse, LessonPlanCourseSyncResult, LessonPlanCreateResponse, LessonPlanOperation, LessonPlanOperationInput, LessonPlanOperationResult, LessonPlanOperationsInput, LessonPlanOperationsResponse, LessonPlanResponse, LessonPlanSyncResult, LessonPlanUpdateStudentItemResponseInput, LessonPlansCreateInput, MakeExternalStudentTestOutAssignmentInput, MakeExternalStudentTestOutAssignmentResponse, MakeExternalTestAssignmentInput, MakeExternalTestAssignmentResponse, PaginationMeta, PlacementQueryParams, PlacementResetUserPlacementInput, PowerPath100ProgressResponse, PowerPath100UpdateResponseResult, PowerPathClientConfig, PowerPathClientInstance, PowerPathLessonType, PowerPathQuestionContent, PowerPathQuestionDifficulty, PowerPathQuestionResult, PowerPathTestQuestion, QuizLikeLessonType, ResetAttemptInput, ResetAttemptResponse, ResetPlacementResponse, ResponseResult, ResponseResultFeedback, ScoreStatus, ScreeningAssignTestInput, ScreeningAssignTestResponse, ScreeningResetSessionInput, ScreeningResetSessionResponse, ScreeningResultsResponse, ScreeningSessionResponse, StandardProgressResponse, StandardUpdateResponseResult, SyllabusQueryParams, SyllabusResponse, TestAssignment, TestAssignmentStatus, TestAssignmentsAdminParams, TestAssignmentsBulkInput, TestAssignmentsCreateInput, TestAssignmentsImportInput, TestAssignmentsListParams, TestAssignmentsListResponse, TestAssignmentsUpdateInput, TestOutParams, TestOutResponse, UpdateStudentItemResponseResult, UpdateStudentQuestionResponseInput, UpdateStudentQuestionResponseResult };
+export type { AuthCheckResult, EnvAuth, Environment, ExplicitAuth, ListParams, PageResult, PowerPathClientConfig, PowerPathClientInstance };