@timeback/core 0.2.1 → 0.2.2-beta.20260320221119

package/dist/index.d.ts

@@ -1,30 +1,1364 @@
+import { CaliperClientInstance } from '@timeback/caliper';
+import { CaseClientInstance } from '@timeback/case';
+import { ClrClientInstance } from '@timeback/clr';
+import { EdubridgeClientInstance } from '@timeback/edubridge';
+import { OneRosterClientInstance } from '@timeback/oneroster';
+import { PowerPathClientInstance } from '@timeback/powerpath';
+import { QtiClientInstance } from '@timeback/qti';
+import { ReportingClientInstance } from '@timeback/reporting';
+import { WebhooksClientInstance } from '@timeback/webhooks';
+
+/**
+ * Interface for obtaining OAuth2 access tokens.
+ *
+ * Implementations handle token caching and refresh automatically.
+ */
+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;
+}
+
+/**
+ * All supported platforms.
+ */
+declare const PLATFORMS$1: readonly ["BEYOND_AI", "LEARNWITH_AI"];
+
+/**
+ * Where Clause Types
+ *
+ * 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
+ * { status: { ne: 'deleted' } }
+ * { score: { gt: 90 } }
+ * { email: { contains: '@school.edu' } }
+ * { role: { in: ['teacher', 'aide'] } }
+ * ```
+ */
+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[];
+}
+/**
+ * A field condition can be:
+ * - A direct value (implies equality)
+ * - An object with operators
+ */
+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>;
+
+/**
+ * Where Clause to Filter String Conversion
+ *
+ * Converts type-safe where clause objects to OneRoster-compatible filter strings.
+ */
+
+/**
+ * Converts a type-safe WhereClause to a OneRoster-compatible filter string.
+ *
+ * This is the primary function for converting the object-based filter syntax
+ * to the string format expected by the OneRoster API.
+ *
+ * @typeParam T - Entity type being filtered
+ * @param where - The where clause object
+ * @returns The filter string, or `undefined` if the clause is empty
+ *
+ * @example
+     * ```typescript
+     * // Simple equality
+     * whereToFilter({ status: 'active' })
+ * // → "status='active'"
+ * ```
+ *
+ * @example
+     * ```typescript
+     * // Multiple fields (implicit AND)
+     * whereToFilter({ status: 'active', role: 'teacher' })
+ * // → "status='active' AND role='teacher'"
+ * ```
+ *
+ * @example
+     * ```typescript
+     * // Comparison operators
+     * whereToFilter({ score: { gte: 90, lte: 100 } })
+ * // → "score>=90 AND score<=100"
+ * ```
+ *
+ * @example
+     * ```typescript
+     * // Not equal
+     * whereToFilter({ status: { ne: 'deleted' } })
+ * // → "status!='deleted'"
+ * ```
+ *
+ * @example
+     * ```typescript
+     * // Contains (substring match)
+     * whereToFilter({ email: { contains: '@school.edu' } })
+ * // → "email~'@school.edu'"
+ * ```
+ *
+ * @example
+     * ```typescript
+     * // Match any value (OR)
+     * whereToFilter({ role: { in: ['teacher', 'aide'] } })
+ * // → "role='teacher' OR role='aide'"
+ * ```
+ *
+ * @example
+     * ```typescript
+     * // Explicit OR across fields
+     * whereToFilter({ OR: [{ role: 'teacher' }, { status: 'active' }] })
+ * // → "role='teacher' OR status='active'"
+ * ```
+ */
+declare function whereToFilter<T>(where: WhereClause<T>): string | undefined;
+
+/**
+ * Shared Types
+ *
+ * Common types for API client infrastructure.
+ */
+
+/**
+ * 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;
+    };
+}
+
+/**
+ * Config Types
+ *
+ * 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$1 = (typeof PLATFORMS$1)[number];
+/**
+ * Supported deployment environments.
+ */
+type Environment$1 = '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$1;
+    /** Target environment */
+    env: Environment$1;
+    /** 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$1;
+    /** 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$1;
+    /** Custom path overrides (takes precedence over pathProfile) */
+    paths?: Partial<PlatformPaths>;
+}
+/**
+ * Union of all provider configuration types.
+ */
+type TimebackProviderConfig = ProviderEnvConfig | ProviderExplicitConfig | ProviderServicesConfig;
+
+/**
+ * Timeback Provider
+ *
+ * Encapsulates platform connection configuration including endpoints and auth.
+ * Providers are complete "connection" objects that clients consume.
+ */
+
+/**
+ * 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: '...' },
+ * })
+ * ```
+ */
+declare class TimebackProvider {
+    /** Platform identifier (if using known platform) */
+    readonly platform?: Platform$1;
+    /** Environment (if using known platform) */
+    readonly env?: Environment$1;
+    /** 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;
+}
+
+/**
+ * Transport Types
+ *
+ * Types for HTTP transport layer.
+ */
+
+/**
+ * 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;
+    };
+}
+
+/**
+ * API Error Classes
+ *
+ * Base error classes for HTTP API failures.
+ * Includes IMS Global error response parsing (OneRoster, QTI, etc.).
+ */
+
+/**
+ * Base error class for all API errors.
+ *
+ * Provides access to the HTTP status code and raw response body.
+ * Includes IMS Global error parsing (minorCodes, details) for
+ * IMS-standard APIs like OneRoster and QTI.
+ *
+ * @example
+     * ```typescript
+     * // Catching and inspecting errors
+     * try {
+ *   await client.users.get('non-existent-id')
+ * } catch (error) {
+ *   if (error instanceof ApiError) {
+ *     console.log(`Error ${error.statusCode}: ${error.message}`)
+ *     console.log('Minor codes:', error.minorCodes)
+ *     console.log('Details:', error.details)
+ *   }
+ * }
+ * ```
+ */
+declare class ApiError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly response?: unknown;
+    readonly name: string;
+    /**
+     * Creates a new ApiError.
+     *
+     * @param message - Human-readable error message
+     * @param statusCode - HTTP status code
+     * @param response - Raw response body (if available)
+     */
+    constructor(message: string, statusCode?: number | undefined, response?: unknown);
+    /**
+     * Minor error codes from IMS Global error response.
+     *
+     * For IMS-standard APIs (OneRoster, QTI), provides specific error codes
+     * like "unknownobject" or "invaliddata".
+     *
+     * @returns Array of field/value pairs, or empty array if not IMS format
+     */
+    get minorCodes(): Array<{
+        field: string;
+        value: string;
+    }>;
+    /**
+     * Additional error details from IMS Global response.
+     *
+     * May contain field-level validation errors or other structured details.
+     *
+     * @returns Array of key-value objects, or empty array if not present
+     */
+    get details(): Array<Record<string, string>>;
+}
+/**
+ * Error thrown when authentication fails (HTTP 401).
+ *
+ * Typically indicates invalid or expired credentials.
+ */
+declare class UnauthorizedError extends ApiError {
+    readonly name = "UnauthorizedError";
+    constructor(message?: string, response?: unknown);
+}
+/**
+ * Error thrown when the client lacks permission for the operation (HTTP 403).
+ *
+ * The credentials are valid, but the client is not authorized for this action.
+ */
+declare class ForbiddenError extends ApiError {
+    readonly name = "ForbiddenError";
+    constructor(message?: string, response?: unknown);
+}
+/**
+ * Error thrown when a requested resource is not found (HTTP 404).
+ */
+declare class NotFoundError extends ApiError {
+    readonly name = "NotFoundError";
+    constructor(message?: string, response?: unknown);
+}
+/**
+ * Error thrown when request data is invalid (HTTP 422).
+ *
+ * Check the `details` property for field-level validation errors.
+ */
+declare class ValidationError extends ApiError {
+    readonly name = "ValidationError";
+    constructor(message?: string, response?: unknown);
+}
+/**
+ * Type guard to check if an error is an ApiError.
+ *
+ * Uses duck typing to work across module boundaries where `instanceof`
+ * may fail due to multiple package copies.
+ * @param error - The error to check
+ * @returns True if error is an ApiError
+ */
+declare function isApiError(error: unknown): error is ApiError;
+
+/**
+ * All supported platforms.
+ */
+declare const PLATFORMS: readonly ["BEYOND_AI", "LEARNWITH_AI"];
+
+/**
+ * Timeback Core Types
+ *
+ * Configuration types for the unified Timeback client,
+ * plus re-exports of entity types from all services.
+ *
+ * @example
+ * ```typescript
+ * import type { User, School, Organization } from '@timeback/core/types'
+ * ```
+ */
+
+/**
+ * Supported Timeback platform implementations.
+ * Derived from the PLATFORMS constant.
+ */
+type Platform = (typeof PLATFORMS)[number];
+/**
+ * Timeback deployment environment.
+ */
+type Environment = 'staging' | 'production';
+/**
+ * Resolved service URLs for environment mode.
+ * @internal
+ */
+interface EnvServiceUrls {
+    oneroster: string;
+    caliper: string;
+    webhooks: string;
+    edubridge: string;
+    qti: string;
+    powerpath?: string;
+    authUrl: string;
+}
+/**
+ * OAuth2 client credentials for environment mode.
+ * Token URL is derived from the environment.
+ */
+interface EnvAuthCredentials {
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * OAuth2 client credentials with explicit token URL.
+ * Required when using baseUrl or services mode.
+ */
+interface ExplicitAuthCredentials {
+    clientId: string;
+    clientSecret: string;
+    authUrl: string;
+}
+/**
+ * Service endpoint configuration.
+ * Can be a simple URL string or an object with baseUrl and optional authUrl override.
+ */
+type ServiceEndpoint = string | {
+    baseUrl: string;
+    authUrl?: string;
+};
+/**
+ * Explicit URLs for each service.
+ * All fields optional — only configure services you need.
+ */
+interface ServiceUrls {
+    /** OneRoster API endpoint */
+    oneroster?: ServiceEndpoint;
+    /** Caliper API endpoint */
+    caliper?: ServiceEndpoint;
+    /** Webhooks API endpoint */
+    webhooks?: ServiceEndpoint;
+    /** Edubridge API endpoint */
+    edubridge?: ServiceEndpoint;
+    /** QTI API endpoint */
+    qti?: ServiceEndpoint;
+    /** PowerPath API endpoint */
+    powerpath?: ServiceEndpoint;
+}
+/**
+ * Environment mode: URLs derived from platform and environment.
+ *
+ * @example
+ * ```typescript
+ * // BeyondAI platform (default)
+ * const client = new TimebackClient({
+ *   env: 'staging',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ *
+ * // LearnWith.AI platform
+ * const client = new TimebackClient({
+ *   platform: 'LEARNWITH_AI',
+ *   env: 'production',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ * ```
+ */
+interface EnvConfig {
+    platform?: Platform;
+    env: Environment;
+    auth?: Partial<EnvAuthCredentials>;
+    timeout?: number;
+}
+/**
+ * Base URL mode: Single base URL, service paths derived automatically.
+ *
+ * @example
+ * ```typescript
+ * const client = new TimebackClient({
+ *   baseUrl: 'https://timeback.myschool.edu',
+ *   auth: {
+ *     clientId: '...',
+ *     clientSecret: '...',
+ *     authUrl: 'https://timeback.myschool.edu/oauth/token',
+ *   },
+ * })
+ * ```
+ */
+interface BaseUrlConfig {
+    baseUrl: string;
+    auth: ExplicitAuthCredentials;
+    timeout?: number;
+}
+/**
+ * Explicit services mode: Full control over each service URL.
+ *
+ * @example
+ * ```typescript
+ * const client = new TimebackClient({
+ *   services: {
+ *     oneroster: 'https://roster.example.com/v1p2',
+ *     caliper: 'https://analytics.example.com/caliper',
+ *     edubridge: 'https://api.example.com/edubridge',
+ *     qti: 'https://qti.example.com/api',
+ *   },
+ *   auth: {
+ *     clientId: '...',
+ *     clientSecret: '...',
+ *     authUrl: 'https://auth.example.com/oauth/token',
+ *   },
+ * })
+ * ```
+ */
+interface ServicesConfig {
+    services: ServiceUrls;
+    auth: ExplicitAuthCredentials;
+    timeout?: number;
+}
+/**
+ * Provider mode: use a pre-built TimebackProvider.
+ *
+ * @example
+ * ```typescript
+ * import { TimebackProvider } from '@timeback/core'
+ *
+ * const provider = new TimebackProvider({
+ *   platform: 'BEYOND_AI',
+ *   env: 'staging',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ *
+ * const client = new TimebackClient({ provider })
+ * ```
+ */
+interface ProviderConfig {
+    provider: TimebackProvider;
+}
+/**
+ * Configuration for the unified Timeback client.
+ *
+ * Supports four modes:
+ * - **Provider**: `{ provider: TimebackProvider }` — pre-built provider
+ * - **Environment**: `{ env: 'staging' | 'production', auth: {...} }`
+ * - **Base URL**: `{ baseUrl: '...', auth: {..., authUrl: '...' } }`
+ * - **Explicit services**: `{ services: {...}, auth: {..., authUrl: '...' } }`
+ */
+type TimebackClientConfig = ProviderConfig | EnvConfig | BaseUrlConfig | ServicesConfig;
+/**
+ * Result of a broadcast operation for a single client.
+ * Similar to PromiseSettledResult but with simpler `ok` boolean.
+ */
+type BroadcastResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: Error;
+};
+/**
+ * Convenience methods available on broadcast results.
+ *
+ * @typeParam T - The value type returned by successful operations
+ * @typeParam TNames - Union of client names (for typed tuples)
+ */
+interface BroadcastResultMethods<T, TNames extends string = string> {
+    /** Get all successful results as [name, value] tuples */
+    readonly succeeded: Array<[TNames, T]>;
+    /** Get all failed results as [name, error] tuples */
+    readonly failed: Array<[TNames, Error]>;
+    /** True if all operations succeeded */
+    readonly allSucceeded: boolean;
+    /** True if any operation failed */
+    readonly anyFailed: boolean;
+    /** Get all successful values (throws if any failed) */
+    values(): T[];
+}
+/**
+ * Broadcast results with both direct property access and convenience methods.
+ *
+ * Access results directly by name or use helper methods:
+ *
+ * @typeParam T - The value type returned by successful operations
+ * @typeParam TNames - Union of client names (enables autocomplete)
+ *
+ * @example
+ * ```typescript
+ * const results = await manager.broadcast(c => c.oneroster.users.create(user))
+ *
+ * // Direct access (like a plain object):
+ * results.alpha.ok
+ * results['beta'].error
+ *
+ * // Convenience methods:
+ * if (results.allSucceeded) {
+ *   console.log('All platforms synced!')
+ * }
+ *
+ * results.succeeded.forEach(([name, user]) => {
+ *   console.log(`Created on ${name}:`, user.id)
+ * })
+ *
+ * results.failed.forEach(([name, error]) => {
+ *   console.error(`Failed on ${name}:`, error.message)
+ * })
+ * ```
+ */
+type BroadcastResults<T, TNames extends string = string> = {
+    [K in TNames]: BroadcastResult<T>;
+} & BroadcastResultMethods<T, TNames>;
+
+/**
+ * Timeback Client
+ *
+ * Unified client for all Timeback education APIs.
+ */
 /**
  * Unified client for Timeback education APIs.
  *
+ * Provides access to all Timeback APIs with shared authentication:
+ * - **OneRoster**: Rostering and gradebook data
+ * - **Edubridge**: Simplified enrollments and analytics
+ * - **Caliper**: Learning analytics events
+ * - **Reporting**: Ad-hoc queries and saved reporting endpoints
+ * - **QTI**: Assessment content management
+ * - **PowerPath**: Placement tests, lesson plans, and assessments
+ * - **CLR**: Comprehensive Learner Record credentials
+ * - **CASE**: Competency and Academic Standards Exchange
+ *
+ * All sub-clients share a single OAuth token, reducing auth requests.
+ *
  * @example
  * ```typescript
- * import { TimebackClient } from '@timeback/core'
+ * // Environment mode
+ * const timeback = new TimebackClient({
+ *   env: 'staging',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ * ```
  *
+ * @example
+ * ```typescript
+ * // Platform selection
  * const timeback = new TimebackClient({
+ *   platform: 'LEARNWITH_AI',
+ *   env: 'production',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Provider mode (pre-built provider)
+ * import { TimebackProvider } from '@timeback/core'
+ *
+ * const provider = new TimebackProvider({
+ *   platform: 'BEYOND_AI',
  *   env: 'staging',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ *
+ * const timeback = new TimebackClient({ provider })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Base URL mode (self-hosted)
+ * const timeback = new TimebackClient({
+ *   baseUrl: 'https://timeback.myschool.edu',
  *   auth: {
- *     clientId: process.env.CLIENT_ID,
- *     clientSecret: process.env.CLIENT_SECRET,
+ *     clientId: '...',
+ *     clientSecret: '...',
+ *     authUrl: 'https://timeback.myschool.edu/oauth/token',
  *   },
  * })
+ * ```
+ */
+declare class TimebackClient {
+    private readonly provider;
+    private _closed;
+    private _oneroster?;
+    private _edubridge?;
+    private _caliper?;
+    private _qti?;
+    private _powerpath?;
+    private _clr?;
+    private _case?;
+    private _reporting?;
+    private _webhooks?;
+    /**
+     * Creates a new Timeback client.
+     *
+     * @param config - Client configuration (env, baseUrl, provider, or services mode).
+     *                 If omitted, reads from TIMEBACK_ENV, TIMEBACK_CLIENT_ID,
+     *                 and TIMEBACK_CLIENT_SECRET environment variables.
+     */
+    constructor(config?: TimebackClientConfig);
+    /**
+     * OneRoster API client for rostering and gradebook operations.
+     *
+     * Lazily initialized on first access. Shares OAuth tokens with other
+     * sub-clients through the provider.
+     *
+     * @returns The OneRoster client instance
+     * @throws {Error} If client has been closed or service not configured
+     */
+    get oneroster(): OneRosterClientInstance;
+    /**
+     * Edubridge API client for simplified enrollments and analytics.
+     *
+     * Lazily initialized on first access. Shares OAuth tokens with other
+     * sub-clients through the provider.
+     *
+     * @returns The Edubridge client instance
+     * @throws {Error} If client has been closed or service not configured
+     */
+    get edubridge(): EdubridgeClientInstance;
+    /**
+     * Caliper API client for learning analytics events.
+     *
+     * Lazily initialized on first access. Shares OAuth tokens with other
+     * sub-clients through the provider.
+     *
+     * @returns The Caliper client instance
+     * @throws {Error} If client has been closed or service not configured
+     */
+    get caliper(): CaliperClientInstance;
+    /**
+     * QTI API client for assessment content management.
+     *
+     * Lazily initialized on first access. Shares OAuth tokens with other
+     * sub-clients through the provider.
+     *
+     * @returns The QTI client instance
+     * @throws {Error} If client has been closed or service not configured
+     */
+    get qti(): QtiClientInstance;
+    /**
+     * PowerPath API client for placement tests and lesson plans.
+     *
+     * Lazily initialized on first access. Shares OAuth tokens with other
+     * sub-clients through the provider.
+     *
+     * @returns The PowerPath client instance
+     * @throws {Error} If client has been closed or service not configured
+     */
+    get powerpath(): PowerPathClientInstance;
+    /**
+     * CLR API client for Comprehensive Learner Record credentials.
+     *
+     * Lazily initialized on first access. Shares OAuth tokens with other
+     * sub-clients through the provider.
+     *
+     * @returns The CLR client instance
+     * @throws {Error} If client has been closed or service not configured
+     */
+    get clr(): ClrClientInstance;
+    /**
+     * CASE API client for Competency and Academic Standards Exchange.
+     *
+     * Lazily initialized on first access. Shares OAuth tokens with other
+     * sub-clients through the provider.
+     *
+     * @returns The CASE client instance
+     * @throws {Error} If client has been closed or service not configured
+     */
+    get case(): CaseClientInstance;
+    /**
+     * Reporting API client for reporting queries and saved reporting endpoints.
+     *
+     * Lazily initialized on first access. Shares OAuth tokens with other
+     * sub-clients through the provider.
+     *
+     * @returns The Reporting client instance
+     * @throws {Error} If client has been closed or service not configured
+     */
+    get reporting(): ReportingClientInstance;
+    /**
+     * Webhooks API client for managing webhook registrations and filters.
+     *
+     * Lazily initialized on first access. Shares OAuth tokens with other
+     * sub-clients through the provider.
+     *
+     * @returns The Webhooks client instance
+     * @throws {Error} If client has been closed or service not configured
+     */
+    get webhooks(): WebhooksClientInstance;
+    /**
+     * 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 client has been closed
+     */
+    checkAuth(): Promise<AuthCheckResult>;
+    /**
+     * Close the client and release resources.
+     *
+     * After calling close():
+     * - Cached OAuth tokens are invalidated
+     * - Sub-client references are cleared
+     * - Further API calls will throw an error
+     */
+    close(): void;
+    /**
+     * Check if the client has been closed.
+     * @returns True if closed
+     */
+    get closed(): boolean;
+    /**
+     * Get the underlying provider for advanced use cases.
+     *
+     * @returns The TimebackProvider instance used by this client
+     */
+    getProvider(): TimebackProvider;
+    /**
+     * Throw if the client has been closed.
+     */
+    private assertOpen;
+    /**
+     * Throw if a service is not configured.
+     * @param service - Service name to check
+     */
+    private assertService;
+}
+
+/**
+ * Timeback Manager
  *
- * for await (const school of timeback.oneroster.schools.list()) {
- *   console.log(school.name)
- * }
+ * Orchestration layer for managing multiple TimebackClient instances.
+ * Enables operations across multiple clients from a single interface.
+ */
+
+/**
+ * Manages multiple TimebackClient instances.
+ *
+ * Use this when you need to:
+ * - Manage multiple clients with different configurations
+ * - Fan-out requests to multiple clients simultaneously
+ * - Aggregate data from multiple sources
+ *
+ * The manager tracks registered client names at the type level,
+ * providing autocomplete for `get()` and `has()`.
+ *
+ * @typeParam TNames - Union of registered client names (tracked automatically)
+ *
+ * @example
+ * ```typescript
+ * const manager = new TimebackManager()
+ *   .register('alpha', { env: 'production', auth: { ... } })
+ *   .register('beta', { env: 'production', auth: { ... } })
+ *
+ * // Autocomplete suggests 'alpha' | 'beta'
+ * const users = await manager.get('alpha').oneroster.users.list()
+ *
+ * // Fan-out to all clients
+ * const results = await manager.broadcast(client => client.oneroster.users.create(user))
+ * // { alpha: { ok: true, value: {...} }, beta: { ok: true, value: {...} } }
  * ```
  */
-export { TimebackClient } from './client';
-export { TimebackManager } from './manager';
-export type { BroadcastResult, BroadcastResultMethods, BroadcastResults } from './types/index';
-export { ApiError, ForbiddenError, isApiError, NotFoundError, UnauthorizedError, ValidationError, } from '@timeback/internal-client-infra';
-export { whereToFilter } from '@timeback/internal-client-infra';
-export type { FieldCondition, FieldOperators, FilterValue, OrCondition, WhereClause, } from '@timeback/internal-client-infra';
-export { getServiceUrlsForEnv } from './constants';
-export type { Environment, EnvServiceUrls, TimebackClientConfig } from './types/index';
-export type { AuthCheckResult } from '@timeback/internal-client-infra';
-//# sourceMappingURL=index.d.ts.map
+declare class TimebackManager<TNames extends string = never> {
+    private readonly clients;
+    /**
+     * Register a new client with a given name.
+     *
+     * Returns a new manager type that includes the registered name,
+     * enabling autocomplete for `get()`.
+     *
+     * @param {string} name - Unique identifier for this client
+     * @param {TimebackClientConfig} config - Configuration for the TimebackClient
+     * @returns {TimebackManager<TNames | N>} - A new manager type that includes the registered name, enabling autocomplete for `get()`
+     * @throws {Error} If a client with this name is already registered
+     */
+    register<N extends string>(name: N, config: TimebackClientConfig): TimebackManager<TNames | N>;
+    /**
+     * Get a registered client by name.
+     *
+     * @param name - The name used when registering the client (autocomplete enabled)
+     * @returns The TimebackClient instance
+     * @throws {Error} If no client with this name is registered
+     *
+     * @example
+     * ```typescript
+     * const client = manager.get('alpha') // autocomplete suggests registered names
+     * const schools = await client.oneroster.schools.list()
+     * ```
+     */
+    get(name: TNames): TimebackClient;
+    /**
+     * Check if a client with the given name is registered.
+     *
+     * Accepts any string since it's a runtime check.
+     * Returns true only for registered names.
+     *
+     * @param name - The name to check
+     * @returns True if registered
+     */
+    has(name: string): name is TNames;
+    /**
+     * Get all registered client names.
+     * @returns Array of registered client names
+     */
+    get names(): string[];
+    /**
+     * Get the number of registered clients.
+     * @returns Number of registered clients
+     */
+    get size(): number;
+    /**
+     * Execute a function on all registered clients.
+     *
+     * Uses `Promise.allSettled` semantics — always completes, never throws.
+     * Each result indicates success or failure per client.
+     *
+     * All operations run in parallel.
+     *
+     * @param fn - Function to execute on each client (name is typed)
+     * @returns BroadcastResults with typed property access and convenience methods
+     *
+     * @example
+     * ```typescript
+     * const results = await manager.broadcast(c => c.oneroster.users.create(user))
+     *
+     * // Typed property access (autocomplete works)
+     * results.alpha.ok
+     *
+     * if (results.allSucceeded) {
+     *   console.log('Synced to all platforms!')
+     * }
+     *
+     * results.succeeded.forEach(([name, user]) => {
+     *   console.log(`Created on ${name}:`, user.id)
+     * })
+     * ```
+     */
+    broadcast<T>(fn: (client: TimebackClient, name: TNames) => T | Promise<T>): Promise<BroadcastResults<T, TNames>>;
+    /**
+     * Unregister and close a client.
+     *
+     * Note: This doesn't update the type — use a new manager if you need
+     * type-safe tracking after unregistration.
+     *
+     * @param name - The name of the client to remove
+     * @returns true if the client was removed, false if it didn't exist
+     */
+    unregister(name: TNames): boolean;
+    /**
+     * Close all registered clients and clear the registry.
+     *
+     * Call this during application shutdown to release resources.
+     */
+    close(): void;
+}
+
+/**
+ * Timeback API Endpoints
+ *
+ * Re-exports URL constants from the internal constants package.
+ */
+
+/**
+ * Get all service URLs for a given platform and environment.
+ *
+ * @param env - Target environment (staging or production)
+ * @param platform - Target platform (defaults to 'BEYOND_AI')
+ * @returns Service URLs for the environment
+ */
+declare function getServiceUrlsForEnv(env: Environment, platform?: Platform): EnvServiceUrls;
+
+export { ApiError, ForbiddenError, NotFoundError, TimebackClient, TimebackManager, TimebackProvider, UnauthorizedError, ValidationError, getServiceUrlsForEnv, isApiError, whereToFilter };
+export type { AuthCheckResult, BroadcastResult, BroadcastResultMethods, BroadcastResults, EnvServiceUrls, Environment, FieldCondition, FieldOperators, FilterValue, OrCondition, TimebackClientConfig, WhereClause };