@timeback/webhooks 0.2.0 → 0.2.1-beta.20260331190459

package/dist/index.d.ts

@@ -1,149 +1,1093 @@
-import * as _timeback_internal_client_infra from '@timeback/internal-client-infra';
-import { BaseTransportConfig, WebhookPaths, ClientConfig, TransportOnlyConfig, RequestOptions, ProviderClientConfig, ProviderRegistry, TimebackProvider, AuthCheckResult, BaseTransport } from '@timeback/internal-client-infra';
-export { AuthCheckResult, EnvAuth, Environment, ExplicitAuth } from '@timeback/internal-client-infra';
-
-type input<T> = T extends {
-    _zod: {
-        input: any;
-    };
-} ? T["_zod"]["input"] : unknown;
+import { WebhookCreateInput, WebhookUpdateInput, WebhookFilterCreateInput, WebhookFilterUpdateInput } from '@timeback/types/zod';
+export { WebhookCreateInput, WebhookFilterCreateInput, WebhookFilterUpdateInput, WebhookUpdateInput } from '@timeback/types/zod';
+import { Webhook, WebhookDeleteResponse, WebhookFilter, WebhookFilterDeleteResponse } from '@timeback/types/protocols/webhooks';
+export { FilterOperation, FilterType, Webhook, WebhookFilter } from '@timeback/types/protocols/webhooks';
 
 /**
- * Webhook Schemas
+ * Interface for obtaining OAuth2 access tokens.
  *
- * Zod schemas for webhook and webhook filter inputs.
+ * 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: readonly ["BEYOND_AI", "LEARNWITH_AI"];
 
+/**
+ * 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.
+ */
+/**
+ * Log severity levels, ordered from least to most severe.
+ *
+ * - debug: Detailed diagnostic information for developers
+ * - info: General operational messages (app started, request received)
+ * - warn: Something unexpected but not breaking (deprecated API used)
+ * - error: Something failed (request failed, database connection lost)
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Runtime environments that determine how logs are formatted.
+ *
+ * - terminal: Local development with colors and icons
+ * - ci: CI/CD pipelines with plain text (no ANSI codes)
+ * - production: JSON lines for log aggregation (DataDog, CloudWatch, etc.)
+ * - browser: Browser console with CSS styling
+ * - test: Test environment with no output
+ */
+type Environment$2 = 'terminal' | 'ci' | 'production' | 'browser' | 'test';
+/**
+ * Arbitrary key-value data attached to log entries.
+ *
+ * Context is merged into log output - in production it becomes top-level
+ * JSON fields, in terminal it's displayed as key=value pairs.
+ *
+ * @example
+ * log.info('User created', { userId: 123, email: 'foo@bar.com' })
+ */
+type LogContext = Record<string, unknown>;
+/**
+ * Configuration options for creating a logger instance.
+ */
+interface LoggerOptions {
+    /**
+     * Logger scope/namespace for categorizing logs.
+     * Child loggers append to this with colons: "api" → "api:users"
+     */
+    scope?: string;
+    /**
+     * Minimum log level to output.
+     * Logs below this level are silently ignored.
+     * @default 'info' (or 'debug' if DEBUG env var is set)
+     */
+    minLevel?: LogLevel;
+    /**
+     * Override automatic environment detection.
+     * Useful for testing or forcing a specific format.
+     */
+    environment?: Environment$2;
+    /**
+     * Default context added to every log entry from this logger.
+     * Useful for request IDs, user IDs, etc.
+     */
+    defaultContext?: LogContext;
+}
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// WEBHOOK INPUTS
-// ═══════════════════════════════════════════════════════════════════════════════
-
-declare const WebhookCreateInput = z
-	.object({
-		name: NonEmptyString,
-		targetUrl: z.url('targetUrl must be a valid URL'),
-		secret: NonEmptyString,
-		active: z.boolean(),
-		sensor: z.string().nullable().optional(),
-		description: z.string().nullable().optional(),
-	})
-	.strict()
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// TYPE EXPORTS (REQUEST INPUTS)
-// ═══════════════════════════════════════════════════════════════════════════════
-
-type WebhookCreateInput = input<typeof WebhookCreateInput>
-
-declare const WebhookUpdateInput = WebhookCreateInput
-type WebhookUpdateInput = input<typeof WebhookUpdateInput>
+/**
+ * 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;
+}
 
-declare const WebhookFilterCreateInput = z
-	.object({
-		webhookId: NonEmptyString,
-		filterKey: NonEmptyString,
-		filterValue: NonEmptyString,
-		filterType: WebhookFilterType,
-		filterOperator: WebhookFilterOperation,
-		active: z.boolean(),
-	})
-	.strict()
-type WebhookFilterCreateInput = input<typeof WebhookFilterCreateInput>
+/**
+ * Shared Types
+ *
+ * Common types for API client infrastructure.
+ */
 
-declare const WebhookFilterUpdateInput = WebhookFilterCreateInput
-type WebhookFilterUpdateInput = input<typeof WebhookFilterUpdateInput>
+/**
+ * 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;
+}
+/**
+ * Auth credentials for explicit mode.
+ * Includes authUrl for custom APIs.
+ * @deprecated Use separate authUrl and ProviderAuth fields instead
+ */
+interface ExplicitAuth$1 {
+    clientId: string;
+    clientSecret: string;
+    authUrl: string;
+}
+/**
+ * Base configuration options shared by all modes.
+ */
+interface BaseConfig$1 {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Custom fetch implementation */
+    fetch?: FetchFn$1;
+}
+/**
+ * Environment-based configuration for Timeback APIs.
+ */
+interface EnvConfig extends BaseConfig$1 {
+    /** Timeback platform implementation (defaults to 'BEYOND_AI') */
+    platform?: Platform$1;
+    /** Target environment - determines base URL and token URL */
+    env: Environment$1;
+    /** OAuth2 client credentials */
+    auth: EnvAuth$1;
+}
+/**
+ * Environment-based configuration with shared token provider.
+ */
+interface TokenProviderEnvConfig extends BaseConfig$1 {
+    /** Timeback platform implementation (defaults to 'BEYOND_AI') */
+    platform?: Platform$1;
+    /** Target environment - determines base URL */
+    env: Environment$1;
+    /** Shared token provider (from @timeback/auth) */
+    tokenProvider: TokenProvider;
+}
+/**
+ * Explicit URL configuration for custom APIs.
+ * Supports both authenticated and public/no-auth services.
+ */
+interface ExplicitConfig extends BaseConfig$1 {
+    /** API base URL */
+    baseUrl: string;
+    /**
+     * OAuth2 token URL. Omit for public/no-auth services.
+     * Can also be provided via auth.authUrl (legacy format).
+     */
+    authUrl?: string;
+    /**
+     * OAuth2 credentials. Required if authUrl is provided.
+     * Supports both ExplicitAuth (with authUrl) and ProviderAuth (without).
+     */
+    auth?: ExplicitAuth$1 | ProviderAuth;
+    /**
+     * Use a built-in path profile by name.
+     * Defaults to 'BEYOND_AI' if neither pathProfile nor paths is specified.
+     */
+    pathProfile?: Platform$1;
+    /** Custom path overrides (takes precedence over pathProfile) */
+    paths?: Partial<PlatformPaths>;
+    /** Not applicable to explicit config — use `EnvConfig` instead */
+    env?: never;
+}
+/**
+ * Use pre-configured transport.
+ */
+interface TransportConfig extends BaseConfig$1 {
+    /** Transport configuration */
+    transport: TransportLike;
+}
+/**
+ * HTTP request options.
+ */
+interface RequestOptions$1 {
+    /** HTTP method */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Query parameters to append to the URL */
+    params?: Record<string, string | number | boolean | undefined>;
+    /** Request body (will be JSON-serialized) */
+    body?: unknown;
+    /** Additional headers to include */
+    headers?: Record<string, string>;
+    /**
+     * Unique identifier for this request.
+     * Used for log correlation and debugging.
+     * Auto-generated if not provided.
+     */
+    requestId?: string;
+}
+/**
+ * Duck-typed transport interface for testing and advanced use.
+ */
+interface TransportLike {
+    /** Base URL of the API */
+    baseUrl: string;
+    /** Make an authenticated request */
+    request<T>(path: string, options?: RequestOptions$1): Promise<T>;
+}
+/**
+ * Configuration using a pre-configured transport.
+ *
+ * For advanced use cases like sharing a transport between clients
+ * or using a custom transport implementation.
+ *
+ * @template T - Transport type (defaults to TransportLike, clients should specify their full transport type)
+ */
+interface TransportOnlyConfig<T extends TransportLike = TransportLike> {
+    /** Existing transport instance */
+    transport: T;
+}
+/**
+ * Union of all client configuration types.
+ */
+type ClientConfig = EnvConfig | TokenProviderEnvConfig | ExplicitConfig | TransportConfig | Partial<ExplicitConfig>;
+/**
+ * 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;
+    };
+}
 
 /**
- * Webhook Types
+ * Config Types
  *
- * Type definitions for the Webhooks API.
+ * Types for TimebackProvider and provider resolution.
  */
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// ENUMS
-// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Caliper API path profile.
+ * Defines paths for Caliper operations. Use `null` for unsupported operations.
+ */
+interface CaliperPaths {
+    /** Path for sending events (POST) */
+    send: string;
+    /** Path for validating events (POST), null if not supported */
+    validate: string | null;
+    /** Path for listing events (GET), null if not supported */
+    list: string | null;
+    /** Path template for getting single event (GET), use {id} placeholder */
+    get: string | null;
+    /** Path template for job status (GET), use {id} placeholder */
+    jobStatus: string | null;
+}
+/**
+ * Webhook API path profile.
+ * Defines paths for webhook management operations.
+ * Nullability is at the platform level (`webhooks: WebhookPaths | null` in PlatformPaths).
+ */
+interface WebhookPaths {
+    /** Path for listing webhooks (GET) */
+    webhookList: string;
+    /** Path template for getting a single webhook (GET), use {id} placeholder */
+    webhookGet: string;
+    /** Path for creating a webhook (POST) */
+    webhookCreate: string;
+    /** Path template for updating a webhook (PUT), use {id} placeholder */
+    webhookUpdate: string;
+    /** Path template for deleting a webhook (DELETE), use {id} placeholder */
+    webhookDelete: string;
+    /** Path template for activating a webhook (PUT), use {id} placeholder */
+    webhookActivate: string;
+    /** Path template for deactivating a webhook (PUT), use {id} placeholder */
+    webhookDeactivate: string;
+    /** Path for listing all webhook filters (GET) */
+    webhookFilterList: string;
+    /** Path template for getting a single webhook filter (GET), use {id} placeholder */
+    webhookFilterGet: string;
+    /** Path for creating a webhook filter (POST) */
+    webhookFilterCreate: string;
+    /** Path template for updating a webhook filter (PUT), use {id} placeholder */
+    webhookFilterUpdate: string;
+    /** Path template for deleting a webhook filter (DELETE), use {id} placeholder */
+    webhookFilterDelete: string;
+    /** Path template for listing filters by webhook (GET), use {webhookId} placeholder */
+    webhookFiltersByWebhook: string;
+}
+/**
+ * Reporting API path profile.
+ * Defines paths for reporting MCP and REST operations.
+ * Nullability is at the platform level (`reporting: ReportingPaths | null` in PlatformPaths).
+ */
+interface ReportingPaths {
+    /** Path for the reporting MCP JSON-RPC endpoint (POST) */
+    mcp: string;
+    /** Path template for executing a saved query (GET), use {id} placeholder */
+    savedQueryExecute: string;
+    /** Path template for checking reporting group membership (GET), use {email} placeholder */
+    adminGroupCheck: string;
+    /** Path template for adding a user to the reporting group (POST), use {email} placeholder */
+    adminGroupAdd: string;
+    /** Path template for removing a user from the reporting group (DELETE), use {email} placeholder */
+    adminGroupRemove: string;
+}
+/**
+ * OneRoster API path profile.
+ * Defines the base path prefix for all OneRoster resources.
+ */
+interface OneRosterPaths {
+    /** Base path prefix for rostering resources (users, schools, classes, etc.) */
+    rostering: string;
+    /** Base path prefix for gradebook resources (lineItems, results, etc.) */
+    gradebook: string;
+    /** Base path prefix for resources API (digital learning resources) */
+    resources: string;
+}
+/**
+ * Edubridge API path profile.
+ * Defines path prefixes for Edubridge operations.
+ */
+interface EdubridgePaths {
+    /** Base path prefix for all Edubridge resources */
+    base: string;
+}
+/**
+ * PowerPath API path profile.
+ * Defines path prefixes for PowerPath operations.
+ */
+interface PowerPathPaths {
+    /** Base path prefix for all PowerPath resources */
+    base: string;
+}
+/**
+ * CASE API path profile.
+ * Defines path prefix for CASE (Competency and Academic Standards Exchange) operations.
+ */
+interface CasePaths {
+    /** Base path prefix for all CASE resources */
+    base: string;
+}
+/**
+ * CLR API path profile.
+ * Defines path prefixes for CLR (Comprehensive Learner Record) operations.
+ */
+interface ClrPaths {
+    /** Path for upserting CLR credentials (POST) */
+    credentials: string;
+    /** Path for API discovery (GET) */
+    discovery: string;
+}
+/**
+ * Platform path profiles for all services.
+ * Use `null` to indicate a service is not supported on the platform.
+ */
+interface PlatformPaths {
+    caliper: CaliperPaths;
+    oneroster: OneRosterPaths;
+    webhooks: WebhookPaths | null;
+    reporting: ReportingPaths | null;
+    edubridge: EdubridgePaths | null;
+    powerpath: PowerPathPaths | null;
+    clr: ClrPaths | null;
+    case: CasePaths | null;
+}
+/**
+ * Services that have path configuration.
+ * Subset of ServiceName - excludes services without path profiles (e.g., 'qti').
+ */
+type PathEnabledService = keyof PlatformPaths;
+/**
+ * Supported Timeback platform implementations.
+ */
+type Platform = (typeof PLATFORMS)[number];
+/**
+ * Supported deployment environments.
+ */
+type Environment = 'staging' | 'production';
+/**
+ * Supported service names.
+ */
+type ServiceName = 'oneroster' | 'caliper' | 'webhooks' | 'reporting' | 'edubridge' | 'qti' | 'powerpath' | 'clr' | 'case';
+/**
+ * Resolved endpoint for a single service.
+ */
+interface ResolvedEndpoint {
+    /** Base URL for the service API */
+    baseUrl: string;
+    /** OAuth2 token URL for this endpoint. Undefined for public/no-auth services. */
+    authUrl?: string;
+}
+/**
+ * Auth credentials for a provider.
+ */
+interface ProviderAuth {
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Configuration for environment-based provider.
+ * Uses known Timeback platform endpoints.
+ */
+interface ProviderEnvConfig {
+    /** Timeback platform (defaults to 'BEYOND_AI') */
+    platform?: Platform;
+    /** Target environment */
+    env: Environment;
+    /** OAuth2 credentials */
+    auth: ProviderAuth;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Configuration for explicit URL provider.
+ * Single base URL for all services.
+ */
+interface ProviderExplicitConfig {
+    /** Base URL for all services */
+    baseUrl: string;
+    /** OAuth2 token URL. Omit for public/no-auth services. */
+    authUrl?: string;
+    /** OAuth2 credentials. Required if authUrl is provided. */
+    auth?: ProviderAuth;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /**
+     * Use a built-in path profile by name.
+     * Defaults to 'BEYOND_AI' if neither pathProfile nor paths is specified.
+     */
+    pathProfile?: Platform;
+    /** Custom path overrides (takes precedence over pathProfile) */
+    paths?: Partial<PlatformPaths>;
+}
+/**
+ * Configuration for multi-service provider.
+ * Different URLs for different services.
+ */
+interface ProviderServicesConfig {
+    /** Per-service base URLs */
+    services: Partial<Record<ServiceName, string>>;
+    /** OAuth2 token URL. Omit for public/no-auth services. */
+    authUrl?: string;
+    /** OAuth2 credentials. Required if authUrl is provided. */
+    auth?: ProviderAuth;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /**
+     * Use a built-in path profile by name.
+     * Defaults to 'BEYOND_AI' if neither pathProfile nor paths is specified.
+     */
+    pathProfile?: Platform;
+    /** Custom path overrides (takes precedence over pathProfile) */
+    paths?: Partial<PlatformPaths>;
+}
+/**
+ * Union of all provider configuration types.
+ */
+type TimebackProviderConfig = ProviderEnvConfig | ProviderExplicitConfig | ProviderServicesConfig;
+/**
+ * Provider template - endpoints without auth.
+ * Used internally to define available platform+env combinations.
+ */
+interface ProviderTemplate {
+    platform: Platform;
+    env: Environment;
+}
+/**
+ * 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 ProviderRegistry {
+    /** Default platform when none specified */
+    defaultPlatform: string;
+    /** Available templates indexed by platform → env */
+    templates: Record<string, Record<string, ProviderTemplate>>;
+}
+/**
+ * Client config that accepts a pre-built provider.
+ */
+interface ProviderClientConfig {
+    /** Pre-built provider */
+    provider: TimebackProvider;
+}
 
-/** Supported data types for webhook filter values */
-type FilterType = 'string' | 'number' | 'boolean'
+/**
+ * Timeback Provider
+ *
+ * Encapsulates platform connection configuration including endpoints and auth.
+ * Providers are complete "connection" objects that clients consume.
+ */
 
-/** Supported filter comparison operations */
-type FilterOperation =
-	| 'eq'
-	| 'neq'
-	| 'gt'
-	| 'gte'
-	| 'lt'
-	| 'lte'
-	| 'contains'
-	| 'notContains'
-	| 'in'
-	| 'notIn'
-	| 'startsWith'
-	| 'endsWith'
-	| 'regexp'
+/**
+ * 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;
+    /** 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;
+}
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// ENTITIES
-// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Transport Types
+ *
+ * Types for HTTP transport layer.
+ */
 
-/** A registered webhook */
-interface Webhook {
-	/** Unique webhook identifier (UUID) */
-	id: string
-	/** Associated sensor identifier, null if not scoped to a sensor */
-	sensor: string | null
-	/** Human-readable webhook name */
-	name: string
-	/** Optional webhook description */
-	description: string | null
-	/** Destination URL that receives event payloads */
-	targetUrl: string
-	/** Shared secret used to sign webhook payloads */
-	secret: string
-	/** Whether the webhook is currently active */
-	active: boolean
-	/** ISO 8601 creation timestamp */
-	created_at: string | null
-	/** ISO 8601 last update timestamp */
-	updated_at: string | null
-	/** ISO 8601 soft-delete timestamp, null if not deleted */
-	deleted_at: string | null
+/**
+ * Fetch function signature for HTTP requests.
+ * Avoids Bun-specific extensions on `typeof fetch`.
+ */
+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;
 }
-
-/** A filter attached to a webhook that controls which events trigger delivery */
-interface WebhookFilter {
-	/** Unique filter identifier (UUID) */
-	id: string
-	/** UUID of the parent webhook */
-	webhookId: string
-	/** Event field to filter on (e.g., 'type', 'action') */
-	filterKey: string
-	/** Value to compare against */
-	filterValue: string
-	/** Data type of the filter value */
-	filterType: FilterType
-	/** Comparison operator */
-	filterOperator: FilterOperation
-	/** Whether the filter is currently active */
-	active: boolean
-	/** ISO 8601 creation timestamp */
-	created_at: string | null
-	/** ISO 8601 last update timestamp */
-	updated_at: string | null
-	/** ISO 8601 soft-delete timestamp, null if not deleted */
-	deleted_at: string | null
+/**
+ * Auth credentials for environment mode.
+ * Token URL is derived automatically from environment.
+ */
+interface EnvAuth {
+    clientId: string;
+    clientSecret: string;
 }
-
-/** Response for DELETE /webhooks/:id */
-interface WebhookDeleteResponse {
-	message: string
+/**
+ * Auth credentials for explicit mode.
+ * Requires explicit authUrl for custom APIs.
+ */
+interface ExplicitAuth {
+    clientId: string;
+    clientSecret: string;
+    authUrl: string;
+}
+/**
+ * Base configuration options shared by all modes.
+ */
+interface BaseConfig {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Custom fetch implementation */
+    fetch?: FetchFn;
+}
+/**
+ * Internal resolved transport configuration.
+ */
+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;
+}
+/**
+ * Transport configuration with explicit auth.
+ */
+interface TransportConfigWithAuth extends BaseConfig {
+    baseUrl: string;
+    auth: ExplicitAuth;
+    tokenProvider?: never;
+}
+/**
+ * Transport configuration with shared token provider.
+ */
+interface TransportConfigWithTokenProvider extends BaseConfig {
+    baseUrl: string;
+    tokenProvider: TokenProvider;
+    auth?: never;
+}
+/**
+ * Transport configuration for public/no-auth services.
+ */
+interface TransportConfigNoAuth extends BaseConfig {
+    baseUrl: string;
+    auth?: never;
+    tokenProvider?: never;
+}
+/**
+ * Configuration for BaseTransport.
+ */
+type BaseTransportConfig = TransportConfigWithAuth | TransportConfigWithTokenProvider | TransportConfigNoAuth;
+/**
+ * Options for creating a BaseTransport.
+ */
+interface BaseTransportOptions {
+    /** Transport configuration */
+    config: BaseTransportConfig;
+    /** Logger instance for request/response logging */
+    logger: Logger;
+}
+/**
+ * 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;
+    };
 }
 
-/** Response for DELETE /webhook-filters/:id */
-interface WebhookFilterDeleteResponse {
-	message: string
+/**
+ * Base Transport Layer
+ *
+ * HTTP transport with OAuth2 authentication, retries, and error handling.
+ * Clients can extend this for protocol-specific features.
+ *
+ */
+/**
+ * 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;
 }
 
 /**
@@ -467,11 +1411,11 @@ declare class WebhookFiltersResource {
 declare const WebhooksClient: {
     new (config?: WebhooksClientConfig): {
         readonly transport: WebhooksTransportLike;
-        readonly _provider?: _timeback_internal_client_infra.TimebackProvider | undefined;
+        readonly _provider?: TimebackProvider | undefined;
         readonly webhooks: WebhooksResource;
         readonly webhookFilters: WebhookFiltersResource;
         getTransport(): WebhooksTransportLike;
-        checkAuth(): Promise<_timeback_internal_client_infra.AuthCheckResult>;
+        checkAuth(): Promise<AuthCheckResult>;
     };
 };
 
@@ -528,5 +1472,5 @@ declare class Transport extends BaseTransport {
     constructor(config: WebhooksTransportConfig);
 }
 
-export { Transport, WebhookCreateInput, WebhookFilterCreateInput, WebhookFilterUpdateInput, WebhookUpdateInput, WebhooksClient, createWebhooksClient };
-export type { FilterOperation, FilterType, Webhook, WebhookFilter, WebhooksClientConfig, WebhooksClientInstance };
+export { Transport, WebhooksClient, createWebhooksClient };
+export type { AuthCheckResult, EnvAuth, Environment, ExplicitAuth, WebhooksClientConfig, WebhooksClientInstance };