@timeback/core 0.2.1 → 0.2.2-beta.20260320221119

package/dist/types.d.ts

@@ -1,10 +1,710 @@
+import * as types from '@timeback/caliper/types';
+export { types as Caliper };
+import * as types$1 from '@timeback/edubridge/types';
+export { types$1 as Edubridge };
+import * as types$2 from '@timeback/oneroster/types';
+export { types$2 as OneRoster };
+import * as types$3 from '@timeback/powerpath/types';
+export { types$3 as PowerPath };
+import * as types$4 from '@timeback/qti/types';
+export { types$4 as Qti };
+import * as types$5 from '@timeback/webhooks/types';
+export { types$5 as Webhooks };
+
 /**
- * All types for the Timeback unified client.
+ * 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"];
+
+/**
+ * Shared Types
+ *
+ * Common types for API client infrastructure.
+ */
+
+/**
+ * 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;
+    };
+}
+
+/**
+ * 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>;
+    /**
+     * 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;
+}
+
+/**
+ * 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
- * import type { TimebackClientConfig, Environment } from '@timeback/core/types'
+ * // 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)
+ * })
  * ```
  */
-export * from './types/index';
-//# sourceMappingURL=types.d.ts.map
+type BroadcastResults<T, TNames extends string = string> = {
+    [K in TNames]: BroadcastResult<T>;
+} & BroadcastResultMethods<T, TNames>;
+
+export type { BaseUrlConfig, BroadcastResult, BroadcastResultMethods, BroadcastResults, EnvAuthCredentials, EnvConfig, EnvServiceUrls, Environment, ExplicitAuthCredentials, Platform, ProviderConfig, ServiceEndpoint, ServiceUrls, ServicesConfig, TimebackClientConfig };