@timeback/sdk 0.1.4

package/dist/server/types.d.ts

@@ -0,0 +1,421 @@
+/**
+ * Server Types
+ *
+ * Configuration and internal types for the server SDK.
+ */
+import type { TimebackClient } from '@timeback/core';
+import type { TimebackAuthUser, TimebackIdentity } from '../shared/types';
+/**
+ * Environment configuration.
+ */
+export type Environment = 'local' | 'staging' | 'production';
+/**
+ * Error codes for Timeback user resolution failures.
+ */
+export type TimebackUserResolutionErrorCode = 'missing_email' | 'timeback_user_not_found' | 'timeback_user_ambiguous' | 'timeback_user_lookup_failed';
+/**
+ * API credentials for Timeback API calls.
+ */
+export interface ApiCredentials {
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * OIDC tokens returned from the identity provider.
+ */
+export interface OIDCTokens {
+    /** Access token for API calls */
+    access_token: string;
+    /** ID token containing user claims */
+    id_token?: string;
+    /** Refresh token for obtaining new access tokens */
+    refresh_token?: string;
+    /** Token type (usually "Bearer") */
+    token_type: string;
+    /** Token expiration in seconds */
+    expires_in?: number;
+}
+/**
+ * Identity provider link info (e.g., Google, Facebook).
+ */
+export interface IdentityProviderLink {
+    /** When the identity was linked */
+    dateCreated: string;
+    /** User ID from the external provider */
+    userId: string;
+    /** Provider name (e.g., "Google", "Facebook") */
+    providerName: string;
+    /** Provider type */
+    providerType: string;
+    /** Issuer URL (if applicable) */
+    issuer: string | null;
+    /** Whether this is the primary identity */
+    primary: string;
+}
+/**
+ * User info claims from the identity provider.
+ */
+export interface OIDCUserInfo {
+    /** Subject identifier (unique user ID from IdP) */
+    sub: string;
+    /** User's email address */
+    email?: string;
+    /** Whether email is verified */
+    email_verified?: boolean | string;
+    /** User's full name */
+    name?: string;
+    /** User's given/first name */
+    given_name?: string;
+    /** User's family/last name */
+    family_name?: string;
+    /** User's profile picture URL */
+    picture?: string;
+    /** Username in the IdP */
+    username?: string;
+    /** Linked identity providers (JSON string from Cognito) */
+    identities?: string | IdentityProviderLink[];
+    /** Additional claims */
+    [key: string]: unknown;
+}
+/**
+ * Context passed to buildState hook.
+ */
+export interface BuildStateContext {
+    /** The incoming sign-in request */
+    req: Request;
+    /** Parsed URL for easy access to query params */
+    url: URL;
+}
+/**
+ * Raw identity provider data (tokens and user info claims).
+ */
+export interface IdpData {
+    /** OIDC tokens from the identity provider */
+    tokens: OIDCTokens;
+    /** User info claims from the identity provider */
+    userInfo: OIDCUserInfo;
+}
+/**
+ * Context passed to onCallbackSuccess hook for full SDK (createTimeback).
+ *
+ * When using `createTimeback()` with SSO mode, the `user` field contains the
+ * enriched `TimebackAuthUser` with `timebackId` as the canonical identifier. Raw IdP
+ * data is available under `idp`.
+ */
+export interface CallbackSuccessContext<TState = unknown> {
+    /** Authenticated user with Timeback profile and IdP claims */
+    user: TimebackAuthUser;
+    /** Raw identity provider data (tokens and user info) */
+    idp: IdpData;
+    /** State data from buildState (if provided) */
+    state: TState | undefined;
+    /** The incoming callback request */
+    req: Request;
+    /** Helper to create a redirect response */
+    redirect: (url: string, headers?: HeadersInit) => Response;
+    /** Helper to create a JSON response */
+    json: <T>(data: T, status?: number, headers?: HeadersInit) => Response;
+}
+/**
+ * Context passed to onCallbackSuccess hook for identity-only SDK (createTimebackIdentity).
+ *
+ * When using `createTimebackIdentity()`, the `user` field contains raw OIDC user info
+ * claims (no Timeback profile enrichment).
+ */
+export interface IdentityOnlyCallbackSuccessContext<TState = unknown> {
+    /** OIDC tokens from the identity provider */
+    tokens: OIDCTokens;
+    /** User info claims from the identity provider */
+    user: OIDCUserInfo;
+    /** State data from buildState (if provided) */
+    state: TState | undefined;
+    /** The incoming callback request */
+    req: Request;
+    /** Helper to create a redirect response */
+    redirect: (url: string, headers?: HeadersInit) => Response;
+    /** Helper to create a JSON response */
+    json: <T>(data: T, status?: number, headers?: HeadersInit) => Response;
+}
+/**
+ * Context passed to onCallbackError hook.
+ */
+export interface CallbackErrorContext<TState = unknown> {
+    /** The error that occurred */
+    error: Error;
+    /** Error code from OIDC provider (if available) */
+    errorCode?: string;
+    /** State data from buildState (if available) */
+    state: TState | undefined;
+    /** The incoming callback request */
+    req: Request;
+    /** Helper to create a redirect response */
+    redirect: (url: string, headers?: HeadersInit) => Response;
+    /** Helper to create a JSON response */
+    json: <T>(data: T, status?: number, headers?: HeadersInit) => Response;
+}
+/**
+ * Base SSO identity configuration fields (shared between full and identity-only).
+ */
+interface BaseSsoIdentityConfig<TState = unknown> {
+    mode: 'sso';
+    /** OIDC client ID */
+    clientId: string;
+    /** OIDC client secret */
+    clientSecret: string;
+    /**
+     * Custom OIDC issuer URL.
+     *
+     * Override the default Timeback IdP URL. Useful for:
+     * - Local development with a mock OIDC server
+     * - Self-hosted Timeback instances
+     *
+     * @example 'http://localhost:3001/mock-oidc'
+     */
+    issuer?: string;
+    /**
+     * Custom OAuth redirect URI.
+     *
+     * Override the auto-computed callback URL. Use when your IdP has
+     * pre-configured callback URLs that differ from the SDK default.
+     *
+     * @example 'http://localhost:5174/api/auth/sso/callback/timeback'
+     */
+    redirectUri?: string;
+    /**
+     * Build custom state to pass through the OIDC flow.
+     *
+     * Use this to preserve data across the redirect (e.g., return URL, invite codes).
+     * State is encoded in the OIDC state parameter and returned in onCallbackSuccess.
+     *
+     * @param ctx - Context with request and parsed URL
+     * @returns State object (will be JSON serialized)
+     *
+     * @example
+     * ```typescript
+     * buildState: ({ url }) => ({
+     *   returnTo: url.searchParams.get('returnTo') ?? '/dashboard',
+     *   inviteId: url.searchParams.get('inviteId'),
+     * })
+     * ```
+     */
+    buildState?: (ctx: BuildStateContext) => TState;
+    /**
+     * Called when OIDC authentication fails.
+     *
+     * @param ctx - Context with error info and helpers
+     * @returns Response (typically a redirect to an error page)
+     *
+     * @example
+     * ```typescript
+     * onCallbackError: ({ error, redirect }) => {
+     *   console.error('SSO failed:', error)
+     *   return redirect('/login?error=sso_failed')
+     * }
+     * ```
+     */
+    onCallbackError?(ctx: CallbackErrorContext<TState>): Promise<Response> | Response;
+    /**
+     * Get the current user from the request.
+     *
+     * This is called by the activity handler to associate activities with users.
+     * Read your session cookie/JWT and return the user, or undefined if not authenticated.
+     *
+     * @param req - The incoming request
+     * @returns User object or undefined
+     *
+     * @example
+     * ```typescript
+     * // Async (with database/session lookup)
+     * getUser: async (req) => {
+     *   const session = await getSession(req)
+     *   if (!session) return undefined
+     *   return { id: session.userId, email: session.email }
+     * }
+     *
+     * // Sync (already have user in memory)
+     * getUser: (req) => currentUser
+     * ```
+     */
+    getUser(req: Request): Promise<TimebackIdentity | undefined> | TimebackIdentity | undefined;
+}
+/**
+ * SSO identity configuration for full SDK (createTimeback).
+ *
+ * When using `createTimeback()`, the SSO callback provides an enriched `TimebackAuthUser`
+ * with `timebackId` as the canonical identifier. The SDK resolves the Timeback
+ * user by email using server API credentials.
+ */
+export interface SsoIdentityConfig<TState = unknown, TSuccessContext = CallbackSuccessContext<TState>> extends BaseSsoIdentityConfig<TState> {
+    /**
+     * Called after successful OIDC authentication and Timeback user resolution.
+     *
+     * The `user` field contains the enriched `TimebackAuthUser` with:
+     * - `id`: Timeback user ID (canonical stable identifier)
+     * - `email`, `name`: User profile data
+     * - `claims`: Raw IdP claims (sub, firstName, lastName, pictureUrl)
+     *
+     * Raw IdP data (tokens, userInfo) is available under `idp`.
+     *
+     * @param ctx - Context with enriched user, IdP data, state, and helpers
+     * @returns Response (typically a redirect)
+     *
+     * @example
+     * ```typescript
+     * onCallbackSuccess: async ({ user, state, redirect }) => {
+     *   // user.id is the timebackId (canonical identifier)
+     *   await setSession({ id: user.id, email: user.email })
+     *   return redirect(state.returnTo ?? '/')
+     * }
+     * ```
+     */
+    onCallbackSuccess(ctx: TSuccessContext): Promise<Response> | Response;
+}
+/**
+ * Custom identity configuration.
+ *
+ * Use when you have your own auth system (Clerk, Auth0, etc.).
+ */
+export interface CustomIdentityConfig {
+    mode: 'custom';
+    /**
+     * Get the current user from the request.
+     *
+     * Read your session cookie/JWT and return the user, or undefined if not authenticated.
+     * Can return synchronously or as a Promise.
+     *
+     * @param req - The incoming request
+     * @returns User object or undefined (sync or async)
+     */
+    getUser(req: Request): Promise<TimebackIdentity | undefined> | TimebackIdentity | undefined;
+}
+/**
+ * Identity configuration (SSO or custom).
+ */
+export type IdentityConfig<TState = unknown> = SsoIdentityConfig<TState> | CustomIdentityConfig;
+/**
+ * Full Timeback SDK configuration.
+ */
+export interface TimebackConfig<TState = unknown> {
+    /** Optional path to timeback.config.ts (auto-discovered if not provided) */
+    configPath?: string;
+    /** Environment */
+    env: Environment;
+    /** API credentials for Timeback API */
+    api: ApiCredentials;
+    /** Identity configuration */
+    identity: IdentityConfig<TState>;
+}
+/**
+ * Request handlers namespace.
+ */
+export interface Handlers {
+    /** Activity submission handler */
+    activity: (req: Request) => Promise<Response>;
+    /** Identity-related handlers */
+    identity: {
+        /** Initiate sign-in (SSO only) */
+        signIn: (req: Request) => Promise<Response>;
+        /** Handle OAuth callback (SSO only) */
+        callback: (req: Request) => Promise<Response>;
+        /** Sign out user */
+        signOut: () => Response;
+    };
+    /** User profile handler */
+    user: {
+        /** Get current user profile */
+        me: (req: Request) => Promise<Response>;
+    };
+}
+/**
+ * App configuration from timeback.config.ts.
+ */
+export interface AppConfig {
+    name: string;
+    sensors: string[];
+    courses: Array<{
+        subject: string;
+        grade: number;
+        courseCode?: string;
+        level?: string;
+        ids?: {
+            staging?: string;
+            production?: string;
+        } | null;
+        metadata?: {
+            goals?: {
+                dailyXp?: number;
+                dailyLessons?: number;
+                dailyActiveMinutes?: number;
+                dailyAccuracy?: number;
+                dailyMasteredUnits?: number;
+            };
+        };
+    }>;
+}
+/**
+ * Timeback SDK instance (framework-agnostic).
+ */
+export interface TimebackInstance<TState = unknown> {
+    /** Configuration */
+    config: TimebackConfig<TState>;
+    /** Request handlers */
+    handle: Handlers;
+    /**
+     * Direct access to the Timeback API client.
+     *
+     * This is an escape hatch for advanced use cases that need to call Timeback
+     * services (OneRoster, Edubridge, Caliper, QTI) beyond what the SDK handlers
+     * provide. The client is created lazily on first access.
+     *
+     * Note: For `env: 'local'`, outbound API calls use `staging` environment.
+     *
+     * @example
+     * ```typescript
+     * // List users from OneRoster
+     * const { data: users } = await timeback.api.oneroster.users.list({ limit: 10 })
+     *
+     * // Send a Caliper event
+     * await timeback.api.caliper.emit(event)
+     * ```
+     */
+    api: TimebackClient;
+}
+/**
+ * Identity-only configuration.
+ *
+ * Use this when you only need SSO authentication without activity tracking
+ * or Timeback API integration.
+ */
+export interface IdentityOnlyConfig<TState = unknown> {
+    /** Environment */
+    env: Environment;
+    /** Identity configuration (SSO mode required for identity-only) */
+    identity: SsoIdentityConfig<TState, IdentityOnlyCallbackSuccessContext<TState>>;
+}
+/**
+ * Identity-only handlers.
+ */
+export interface IdentityOnlyHandlers {
+    /** Identity-related handlers */
+    identity: {
+        /** Initiate sign-in */
+        signIn: (req: Request) => Promise<Response>;
+        /** Handle OAuth callback */
+        callback: (req: Request) => Promise<Response>;
+        /** Sign out user */
+        signOut: () => Response;
+    };
+}
+/**
+ * Identity-only SDK instance.
+ *
+ * Returned by `createTimebackIdentity()` for SSO-only integrations.
+ */
+export interface IdentityOnlyInstance<TState = unknown> {
+    /** Configuration */
+    config: IdentityOnlyConfig<TState>;
+    /** Request handlers (identity only) */
+    handle: IdentityOnlyHandlers;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/server/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}

package/dist/shared/constants.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared Constants
+ */
+/** Default base path for Timeback API routes */
+export declare const DEFAULT_BASE_PATH = "/api/timeback";
+/** API route paths */
+export declare const ROUTES: {
+    readonly ACTIVITY: "/activity";
+    readonly IDENTITY: {
+        readonly SIGNIN: "/identity/signin";
+        readonly SIGNOUT: "/identity/signout";
+        readonly CALLBACK: "/identity/callback";
+    };
+    readonly USER: {
+        readonly ME: "/user/me";
+    };
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/shared/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/shared/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,gDAAgD;AAChD,eAAO,MAAM,iBAAiB,kBAAkB,CAAA;AAEhD,sBAAsB;AACtB,eAAO,MAAM,MAAM;;;;;;;;;;CAUT,CAAA"}

package/dist/shared/types.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Shared Types
+ *
+ * Types shared between client and server.
+ */
+import type { TimebackGrade, TimebackSubject } from '@timeback/types';
+/**
+ * User identity returned from SSO.
+ */
+export interface TimebackIdentity {
+    id: string;
+    email: string;
+    name?: string;
+}
+/**
+ * Timeback user profile with enriched data from the Timeback API.
+ */
+export interface TimebackProfile {
+    /** Timeback user ID */
+    id: string;
+    /** User's email address */
+    email: string;
+    /** User's display name */
+    name?: string;
+    /** School information */
+    school?: {
+        id: string;
+        name: string;
+    };
+    /** Grade level */
+    grade?: number;
+    /** XP earned on this app */
+    xp?: {
+        /** XP earned today (UTC day range) */
+        today: number;
+        /** XP earned across all time (computed from analytics) */
+        all: number;
+    };
+    /** Enrolled courses */
+    courses?: Array<{
+        id: string;
+        code: string;
+        name: string;
+    }>;
+    /** Goals and progress */
+    goals?: {
+        dailyXp?: number;
+        dailyLessons?: number;
+        dailyActiveMinutes?: number;
+    };
+}
+/**
+ * Recommended minimal user payload to persist in a session.
+ *
+ * **User-facing note:** this type is part of the SDK’s developer experience.
+ * It exists to give you a “safe default” session shape that works well for
+ * cookie-based sessions (small payload) while still carrying enough Timeback
+ * context to power common UI affordances (e.g. showing a school name or grade).
+ *
+ * **What it is:** a minimal, serializable subset of `TimebackProfile`.
+ * **What it isn’t:** a guarantee that you’ll always have the full Timeback
+ * profile (courses, goals, xp, etc.) in-session. If you need richer data, fetch
+ * it from the API (e.g. `timeback.user.fetch()`) and cache/store it according
+ * to your app’s needs.
+ *
+ * **Stability:** this is still early and we’re actively iterating on identity
+ * and session ergonomics. We may rename, restructure, or remove this type from
+ * the public surface as the SDK evolves.
+ */
+export type TimebackSessionUser = Pick<TimebackProfile, 'id' | 'email' | 'name' | 'school' | 'grade'>;
+/**
+ * Claims from the identity provider (IdP).
+ *
+ * Normalized subset of OIDC UserInfo claims.
+ */
+export interface IdentityClaims {
+    /** Subject identifier (unique user ID from IdP) */
+    sub: string;
+    /** User's email address */
+    email: string;
+    /** User's first/given name */
+    firstName?: string;
+    /** User's last/family name */
+    lastName?: string;
+    /** User's profile picture URL */
+    pictureUrl?: string;
+}
+/**
+ * Authenticated user with Timeback profile and IdP claims.
+ *
+ * This is the primary user object returned during SSO callback when using
+ * `createTimeback()`. The `id` field is the canonical `timebackId` (stable identifier).
+ */
+export interface TimebackAuthUser extends TimebackProfile {
+    /** IdP claims (raw identity provider data) */
+    claims: IdentityClaims;
+}
+/**
+ * Course selector for activity tracking.
+ *
+ * This should correspond to a unique course entry in `timeback.config.ts`.
+ */
+export interface ActivityCourseRef {
+    subject: TimebackSubject;
+    grade: TimebackGrade;
+}
+/**
+ * Activity start parameters.
+ */
+export interface ActivityParams {
+    /** Unique identifier for the learning object */
+    id: string;
+    /** Display name of the activity */
+    name: string;
+    /** Course selector (must match a unique course in timeback.config.ts) */
+    course: ActivityCourseRef;
+}
+/**
+ * Activity metrics (optional performance data).
+ */
+export interface ActivityMetrics {
+    /** Total questions attempted */
+    totalQuestions?: number;
+    /** Number of correct answers */
+    correctQuestions?: number;
+    /** XP earned from this activity */
+    xpEarned?: number;
+    /** Number of units mastered */
+    masteredUnits?: number;
+}
+/**
+ * Activity state sent to the server when ending.
+ */
+export interface ActivityEndPayload {
+    /** Unique identifier for the learning object */
+    id: string;
+    /** Display name of the activity */
+    name: string;
+    /** Course selector (must match a unique course in timeback.config.ts) */
+    course: ActivityCourseRef;
+    /** ISO 8601 timestamp when activity started */
+    startedAt: string;
+    /** ISO 8601 timestamp when activity ended */
+    endedAt: string;
+    /** Active time in milliseconds (excluding paused time) */
+    elapsedMs: number;
+    /** Total paused time in milliseconds */
+    pausedMs: number;
+    /** Activity metrics */
+    metrics: ActivityMetrics;
+}
+/**
+ * Activity submission response.
+ */
+export interface ActivityResponse {
+    success: boolean;
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAErE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,yBAAyB;IACzB,MAAM,CAAC,EAAE;QACR,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,MAAM,CAAA;KACZ,CAAA;IAED,kBAAkB;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd,4BAA4B;IAC5B,EAAE,CAAC,EAAE;QACJ,sCAAsC;QACtC,KAAK,EAAE,MAAM,CAAA;QACb,0DAA0D;QAC1D,GAAG,EAAE,MAAM,CAAA;KACX,CAAA;IAED,uBAAuB;IACvB,OAAO,CAAC,EAAE,KAAK,CAAC;QACf,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,MAAM,CAAA;QACZ,IAAI,EAAE,MAAM,CAAA;KACZ,CAAC,CAAA;IAEF,yBAAyB;IACzB,KAAK,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,YAAY,CAAC,EAAE,MAAM,CAAA;QACrB,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAC3B,CAAA;CACD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACrC,eAAe,EACf,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAC5C,CAAA;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAA;IACX,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iCAAiC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACxD,8CAA8C;IAC9C,MAAM,EAAE,cAAc,CAAA;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,eAAe,CAAA;IACxB,KAAK,EAAE,aAAa,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAA;IACV,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,yEAAyE;IACzE,MAAM,EAAE,iBAAiB,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,gCAAgC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gCAAgC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,+BAA+B;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAA;IACV,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,yEAAyE;IACzE,MAAM,EAAE,iBAAiB,CAAA;IACzB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAA;IACf,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAA;IACjB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAA;IAChB,uBAAuB;IACvB,OAAO,EAAE,eAAe,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;CACd"}