@legendsoflearning/lol-sdk-core 0.1.0

package/dist/index-vM3xPKfV.d.mts

@@ -0,0 +1,173 @@
+/**
+ * API endpoint definitions for Legends of Learning backend.
+ */
+type ApiType = 'teachers' | 'parents' | 'play' | 'public' | 'developers' | 'admin';
+interface ApiEndpoint {
+    graphql: string;
+    websocket?: string;
+    description: string;
+}
+declare const API_ENDPOINTS: Record<ApiType, ApiEndpoint>;
+
+/**
+ * Core type definitions for the Legends SDK.
+ */
+
+interface QueryOptions<TVariables = Record<string, unknown>> {
+    variables?: TVariables;
+    fetchPolicy?: 'cache-first' | 'network-only' | 'cache-only' | 'no-cache';
+    errorPolicy?: 'none' | 'ignore' | 'all';
+}
+interface QueryResult<TData> {
+    data: TData;
+    loading: boolean;
+    error?: Error;
+    networkStatus: number;
+}
+interface MutationOptions<TVariables = Record<string, unknown>> {
+    variables?: TVariables;
+    optimisticResponse?: unknown;
+    refetchQueries?: string[];
+    awaitRefetchQueries?: boolean;
+}
+interface MutationResult<TData> {
+    data?: TData;
+    loading: boolean;
+    error?: Error;
+    called: boolean;
+}
+interface SubscriptionOptions<TVariables = Record<string, unknown>> {
+    variables?: TVariables;
+    shouldResubscribe?: boolean;
+}
+interface Session {
+    user: {
+        id: string;
+        email?: string;
+        firstName?: string;
+        lastName?: string;
+        role?: string;
+    };
+    token?: string;
+    expiresAt: Date;
+}
+interface Credentials {
+    email: string;
+    password: string;
+    rememberMe?: boolean;
+}
+interface SignUpInput {
+    email: string;
+    password: string;
+    firstName: string;
+    lastName: string;
+    agreedToTerms?: boolean;
+}
+interface AuthResult {
+    success: boolean;
+    session?: Session;
+    error?: string;
+}
+type OAuthProvider = 'google' | 'clever' | 'canvas' | 'classlink';
+type Unsubscribe = () => void;
+type AuthCallback = (session: Session | null) => void;
+
+/**
+ * Authentication module for the Legends SDK.
+ *
+ * Supports two auth modes:
+ * - 'cookie' (default): Uses session cookies, best for same-domain apps
+ * - 'token': Uses X-Session-Token header, works cross-domain
+ */
+
+type AuthMode = 'cookie' | 'token';
+interface AuthConfig {
+    /**
+     * Authentication mode.
+     * - 'cookie': Uses session cookies (same-domain only)
+     * - 'token': Uses X-Session-Token header (cross-domain)
+     * @default 'cookie'
+     */
+    mode?: AuthMode;
+    /**
+     * Storage mechanism for session data.
+     * @default 'localStorage'
+     */
+    storage?: 'localStorage' | 'sessionStorage' | 'memory' | Storage;
+    /**
+     * Auto-refresh tokens before expiry.
+     * @default true
+     */
+    autoRefresh?: boolean;
+    /**
+     * Callback when auth state changes.
+     */
+    onAuthChange?: AuthCallback;
+    /**
+     * Client ID for OAuth flows (for registered third-party apps).
+     */
+    clientId?: string;
+    /**
+     * Redirect URI for OAuth flows.
+     * @default window.location.origin + '/auth/callback'
+     */
+    redirectUri?: string;
+}
+interface Auth {
+    /**
+     * Sign in with email and password.
+     */
+    signIn(credentials: Credentials): Promise<AuthResult>;
+    /**
+     * Sign up with email, password, and profile info.
+     */
+    signUp(input: SignUpInput): Promise<AuthResult>;
+    /**
+     * Sign in with OAuth provider.
+     * For third-party apps, this initiates the OAuth authorization flow.
+     */
+    signInWithOAuth(provider: OAuthProvider): Promise<AuthResult>;
+    /**
+     * Handle OAuth callback (for third-party apps).
+     * Call this on your redirect_uri page to complete the OAuth flow.
+     */
+    handleOAuthCallback(params: {
+        code?: string;
+        error?: string;
+    }): Promise<AuthResult>;
+    /**
+     * Sign out and clear session.
+     */
+    signOut(): Promise<void>;
+    /**
+     * Get the current session.
+     */
+    getSession(): Session | null;
+    /**
+     * Get auth headers for API requests (token mode only).
+     * Returns headers object with X-Session-Token if authenticated.
+     */
+    getAuthHeaders(): Record<string, string>;
+    /**
+     * Get the current auth mode.
+     */
+    getMode(): AuthMode;
+    /**
+     * Subscribe to auth state changes.
+     */
+    onAuthChange(callback: AuthCallback): Unsubscribe;
+    /**
+     * Refresh the current token.
+     */
+    refreshToken(): Promise<Session | null>;
+    /**
+     * @internal Handle auth errors from the API.
+     */
+    _handleAuthError(): void;
+}
+declare function createAuth(config: AuthConfig & {
+    api: ApiType;
+    baseUrl: string;
+}): Auth;
+
+export { type ApiType as A, type Credentials as C, type MutationOptions as M, type OAuthProvider as O, type QueryOptions as Q, type SubscriptionOptions as S, type AuthConfig as a, type QueryResult as b, type MutationResult as c, type Auth as d, type ApiEndpoint as e, API_ENDPOINTS as f, type AuthMode as g, type Session as h, type SignUpInput as i, type AuthResult as j, createAuth as k };

package/dist/index-vM3xPKfV.d.ts

@@ -0,0 +1,173 @@
+/**
+ * API endpoint definitions for Legends of Learning backend.
+ */
+type ApiType = 'teachers' | 'parents' | 'play' | 'public' | 'developers' | 'admin';
+interface ApiEndpoint {
+    graphql: string;
+    websocket?: string;
+    description: string;
+}
+declare const API_ENDPOINTS: Record<ApiType, ApiEndpoint>;
+
+/**
+ * Core type definitions for the Legends SDK.
+ */
+
+interface QueryOptions<TVariables = Record<string, unknown>> {
+    variables?: TVariables;
+    fetchPolicy?: 'cache-first' | 'network-only' | 'cache-only' | 'no-cache';
+    errorPolicy?: 'none' | 'ignore' | 'all';
+}
+interface QueryResult<TData> {
+    data: TData;
+    loading: boolean;
+    error?: Error;
+    networkStatus: number;
+}
+interface MutationOptions<TVariables = Record<string, unknown>> {
+    variables?: TVariables;
+    optimisticResponse?: unknown;
+    refetchQueries?: string[];
+    awaitRefetchQueries?: boolean;
+}
+interface MutationResult<TData> {
+    data?: TData;
+    loading: boolean;
+    error?: Error;
+    called: boolean;
+}
+interface SubscriptionOptions<TVariables = Record<string, unknown>> {
+    variables?: TVariables;
+    shouldResubscribe?: boolean;
+}
+interface Session {
+    user: {
+        id: string;
+        email?: string;
+        firstName?: string;
+        lastName?: string;
+        role?: string;
+    };
+    token?: string;
+    expiresAt: Date;
+}
+interface Credentials {
+    email: string;
+    password: string;
+    rememberMe?: boolean;
+}
+interface SignUpInput {
+    email: string;
+    password: string;
+    firstName: string;
+    lastName: string;
+    agreedToTerms?: boolean;
+}
+interface AuthResult {
+    success: boolean;
+    session?: Session;
+    error?: string;
+}
+type OAuthProvider = 'google' | 'clever' | 'canvas' | 'classlink';
+type Unsubscribe = () => void;
+type AuthCallback = (session: Session | null) => void;
+
+/**
+ * Authentication module for the Legends SDK.
+ *
+ * Supports two auth modes:
+ * - 'cookie' (default): Uses session cookies, best for same-domain apps
+ * - 'token': Uses X-Session-Token header, works cross-domain
+ */
+
+type AuthMode = 'cookie' | 'token';
+interface AuthConfig {
+    /**
+     * Authentication mode.
+     * - 'cookie': Uses session cookies (same-domain only)
+     * - 'token': Uses X-Session-Token header (cross-domain)
+     * @default 'cookie'
+     */
+    mode?: AuthMode;
+    /**
+     * Storage mechanism for session data.
+     * @default 'localStorage'
+     */
+    storage?: 'localStorage' | 'sessionStorage' | 'memory' | Storage;
+    /**
+     * Auto-refresh tokens before expiry.
+     * @default true
+     */
+    autoRefresh?: boolean;
+    /**
+     * Callback when auth state changes.
+     */
+    onAuthChange?: AuthCallback;
+    /**
+     * Client ID for OAuth flows (for registered third-party apps).
+     */
+    clientId?: string;
+    /**
+     * Redirect URI for OAuth flows.
+     * @default window.location.origin + '/auth/callback'
+     */
+    redirectUri?: string;
+}
+interface Auth {
+    /**
+     * Sign in with email and password.
+     */
+    signIn(credentials: Credentials): Promise<AuthResult>;
+    /**
+     * Sign up with email, password, and profile info.
+     */
+    signUp(input: SignUpInput): Promise<AuthResult>;
+    /**
+     * Sign in with OAuth provider.
+     * For third-party apps, this initiates the OAuth authorization flow.
+     */
+    signInWithOAuth(provider: OAuthProvider): Promise<AuthResult>;
+    /**
+     * Handle OAuth callback (for third-party apps).
+     * Call this on your redirect_uri page to complete the OAuth flow.
+     */
+    handleOAuthCallback(params: {
+        code?: string;
+        error?: string;
+    }): Promise<AuthResult>;
+    /**
+     * Sign out and clear session.
+     */
+    signOut(): Promise<void>;
+    /**
+     * Get the current session.
+     */
+    getSession(): Session | null;
+    /**
+     * Get auth headers for API requests (token mode only).
+     * Returns headers object with X-Session-Token if authenticated.
+     */
+    getAuthHeaders(): Record<string, string>;
+    /**
+     * Get the current auth mode.
+     */
+    getMode(): AuthMode;
+    /**
+     * Subscribe to auth state changes.
+     */
+    onAuthChange(callback: AuthCallback): Unsubscribe;
+    /**
+     * Refresh the current token.
+     */
+    refreshToken(): Promise<Session | null>;
+    /**
+     * @internal Handle auth errors from the API.
+     */
+    _handleAuthError(): void;
+}
+declare function createAuth(config: AuthConfig & {
+    api: ApiType;
+    baseUrl: string;
+}): Auth;
+
+export { type ApiType as A, type Credentials as C, type MutationOptions as M, type OAuthProvider as O, type QueryOptions as Q, type SubscriptionOptions as S, type AuthConfig as a, type QueryResult as b, type MutationResult as c, type Auth as d, type ApiEndpoint as e, API_ENDPOINTS as f, type AuthMode as g, type Session as h, type SignUpInput as i, type AuthResult as j, createAuth as k };

package/dist/index.d.mts

@@ -0,0 +1,154 @@
+import { InMemoryCacheConfig, TypedDocumentNode, NormalizedCacheObject, ApolloClient } from '@apollo/client';
+import { A as ApiType, a as AuthConfig, Q as QueryOptions, b as QueryResult, M as MutationOptions, c as MutationResult, d as Auth } from './index-vM3xPKfV.mjs';
+export { f as API_ENDPOINTS, e as ApiEndpoint, g as AuthMode, j as AuthResult, C as Credentials, O as OAuthProvider, h as Session, i as SignUpInput, S as SubscriptionOptions } from './index-vM3xPKfV.mjs';
+
+/**
+ * Logging utilities for the Legends SDK.
+ */
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4
+}
+interface Logger {
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+interface LoggerConfig {
+    level: LogLevel;
+    prefix?: string;
+}
+declare function createLogger(config?: Partial<LoggerConfig>): Logger;
+
+/**
+ * Main client implementation for the Legends SDK.
+ */
+
+interface LolClientConfig {
+    /**
+     * Which API to connect to.
+     */
+    api: ApiType;
+    /**
+     * Base URL for the API. Defaults to production.
+     */
+    baseUrl?: string;
+    /**
+     * OAuth client ID for third-party apps.
+     */
+    clientId?: string;
+    /**
+     * Authentication mode: 'cookie' (same-domain) or 'token' (cross-domain).
+     */
+    mode?: 'cookie' | 'token';
+    /**
+     * Authentication configuration.
+     */
+    auth?: AuthConfig;
+    /**
+     * Apollo cache configuration.
+     */
+    cache?: InMemoryCacheConfig;
+    /**
+     * Global error handler.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Enable debug logging.
+     */
+    debug?: boolean;
+    /**
+     * Log level.
+     */
+    logLevel?: LogLevel;
+    /**
+     * Custom logger implementation.
+     */
+    logger?: Logger;
+    /**
+     * Enable SSR mode.
+     */
+    ssr?: boolean;
+    /**
+     * Cookies for SSR (from request).
+     */
+    cookie?: string;
+}
+interface LolClient<_TApi extends ApiType = ApiType> {
+    /**
+     * Execute a GraphQL query.
+     */
+    query<TData, TVariables extends Record<string, unknown>>(document: TypedDocumentNode<TData, TVariables>, options?: QueryOptions<TVariables>): Promise<QueryResult<TData>>;
+    /**
+     * Execute a GraphQL mutation.
+     */
+    mutate<TData, TVariables extends Record<string, unknown>>(document: TypedDocumentNode<TData, TVariables>, options?: MutationOptions<TVariables>): Promise<MutationResult<TData>>;
+    /**
+     * Authentication module.
+     */
+    auth: Auth;
+    /**
+     * Cache operations.
+     */
+    cache: {
+        read<TData>(document: TypedDocumentNode<TData, Record<string, unknown>>): TData | null;
+        write<TData>(document: TypedDocumentNode<TData, Record<string, unknown>>, data: TData): void;
+        evict(id: string): boolean;
+        reset(): Promise<void>;
+        clear(): Promise<void>;
+        extract(): NormalizedCacheObject;
+        restore(data: NormalizedCacheObject): void;
+    };
+    /**
+     * Get the underlying Apollo client.
+     */
+    getApolloClient(): ApolloClient<NormalizedCacheObject>;
+}
+declare function createClient<TApi extends ApiType>(config: LolClientConfig & {
+    api: TApi;
+}): LolClient<TApi>;
+declare const APOLLO_STATE_PROP_NAME = "__APOLLO_STATE__";
+declare function addApolloState<P extends Record<string, unknown>>(client: LolClient, pageProps: {
+    props: P;
+}): {
+    props: P & {
+        [APOLLO_STATE_PROP_NAME]: NormalizedCacheObject;
+    };
+};
+declare function initializeClientWithState<TApi extends ApiType>(config: LolClientConfig & {
+    api: TApi;
+}, initialState?: NormalizedCacheObject): LolClient<TApi>;
+
+/**
+ * Error types for the Legends SDK.
+ */
+type ErrorCode = 'NOT_AUTHENTICATED' | 'NOT_AUTHORIZED' | 'NOT_FOUND' | 'VALIDATION_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'UNKNOWN';
+declare class LolError extends Error {
+    readonly code: ErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code?: ErrorCode, details?: Record<string, unknown>);
+}
+declare class AuthError extends LolError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class NetworkError extends LolError {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number, details?: Record<string, unknown>);
+}
+declare class GraphQLError extends LolError {
+    readonly locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    readonly path?: string[];
+    constructor(message: string, code: ErrorCode, locations?: Array<{
+        line: number;
+        column: number;
+    }>, path?: string[], details?: Record<string, unknown>);
+}
+
+export { APOLLO_STATE_PROP_NAME, ApiType, Auth, AuthConfig, AuthError, type ErrorCode, GraphQLError, LogLevel, type Logger, type LolClient, type LolClientConfig, LolError, MutationOptions, MutationResult, NetworkError, QueryOptions, QueryResult, addApolloState, createClient, createLogger, initializeClientWithState };

package/dist/index.d.ts

@@ -0,0 +1,154 @@
+import { InMemoryCacheConfig, TypedDocumentNode, NormalizedCacheObject, ApolloClient } from '@apollo/client';
+import { A as ApiType, a as AuthConfig, Q as QueryOptions, b as QueryResult, M as MutationOptions, c as MutationResult, d as Auth } from './index-vM3xPKfV.js';
+export { f as API_ENDPOINTS, e as ApiEndpoint, g as AuthMode, j as AuthResult, C as Credentials, O as OAuthProvider, h as Session, i as SignUpInput, S as SubscriptionOptions } from './index-vM3xPKfV.js';
+
+/**
+ * Logging utilities for the Legends SDK.
+ */
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4
+}
+interface Logger {
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+interface LoggerConfig {
+    level: LogLevel;
+    prefix?: string;
+}
+declare function createLogger(config?: Partial<LoggerConfig>): Logger;
+
+/**
+ * Main client implementation for the Legends SDK.
+ */
+
+interface LolClientConfig {
+    /**
+     * Which API to connect to.
+     */
+    api: ApiType;
+    /**
+     * Base URL for the API. Defaults to production.
+     */
+    baseUrl?: string;
+    /**
+     * OAuth client ID for third-party apps.
+     */
+    clientId?: string;
+    /**
+     * Authentication mode: 'cookie' (same-domain) or 'token' (cross-domain).
+     */
+    mode?: 'cookie' | 'token';
+    /**
+     * Authentication configuration.
+     */
+    auth?: AuthConfig;
+    /**
+     * Apollo cache configuration.
+     */
+    cache?: InMemoryCacheConfig;
+    /**
+     * Global error handler.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Enable debug logging.
+     */
+    debug?: boolean;
+    /**
+     * Log level.
+     */
+    logLevel?: LogLevel;
+    /**
+     * Custom logger implementation.
+     */
+    logger?: Logger;
+    /**
+     * Enable SSR mode.
+     */
+    ssr?: boolean;
+    /**
+     * Cookies for SSR (from request).
+     */
+    cookie?: string;
+}
+interface LolClient<_TApi extends ApiType = ApiType> {
+    /**
+     * Execute a GraphQL query.
+     */
+    query<TData, TVariables extends Record<string, unknown>>(document: TypedDocumentNode<TData, TVariables>, options?: QueryOptions<TVariables>): Promise<QueryResult<TData>>;
+    /**
+     * Execute a GraphQL mutation.
+     */
+    mutate<TData, TVariables extends Record<string, unknown>>(document: TypedDocumentNode<TData, TVariables>, options?: MutationOptions<TVariables>): Promise<MutationResult<TData>>;
+    /**
+     * Authentication module.
+     */
+    auth: Auth;
+    /**
+     * Cache operations.
+     */
+    cache: {
+        read<TData>(document: TypedDocumentNode<TData, Record<string, unknown>>): TData | null;
+        write<TData>(document: TypedDocumentNode<TData, Record<string, unknown>>, data: TData): void;
+        evict(id: string): boolean;
+        reset(): Promise<void>;
+        clear(): Promise<void>;
+        extract(): NormalizedCacheObject;
+        restore(data: NormalizedCacheObject): void;
+    };
+    /**
+     * Get the underlying Apollo client.
+     */
+    getApolloClient(): ApolloClient<NormalizedCacheObject>;
+}
+declare function createClient<TApi extends ApiType>(config: LolClientConfig & {
+    api: TApi;
+}): LolClient<TApi>;
+declare const APOLLO_STATE_PROP_NAME = "__APOLLO_STATE__";
+declare function addApolloState<P extends Record<string, unknown>>(client: LolClient, pageProps: {
+    props: P;
+}): {
+    props: P & {
+        [APOLLO_STATE_PROP_NAME]: NormalizedCacheObject;
+    };
+};
+declare function initializeClientWithState<TApi extends ApiType>(config: LolClientConfig & {
+    api: TApi;
+}, initialState?: NormalizedCacheObject): LolClient<TApi>;
+
+/**
+ * Error types for the Legends SDK.
+ */
+type ErrorCode = 'NOT_AUTHENTICATED' | 'NOT_AUTHORIZED' | 'NOT_FOUND' | 'VALIDATION_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'UNKNOWN';
+declare class LolError extends Error {
+    readonly code: ErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code?: ErrorCode, details?: Record<string, unknown>);
+}
+declare class AuthError extends LolError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class NetworkError extends LolError {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number, details?: Record<string, unknown>);
+}
+declare class GraphQLError extends LolError {
+    readonly locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    readonly path?: string[];
+    constructor(message: string, code: ErrorCode, locations?: Array<{
+        line: number;
+        column: number;
+    }>, path?: string[], details?: Record<string, unknown>);
+}
+
+export { APOLLO_STATE_PROP_NAME, ApiType, Auth, AuthConfig, AuthError, type ErrorCode, GraphQLError, LogLevel, type Logger, type LolClient, type LolClientConfig, LolError, MutationOptions, MutationResult, NetworkError, QueryOptions, QueryResult, addApolloState, createClient, createLogger, initializeClientWithState };