cc-lark 0.1.1

package/dist/core/api-error.js

@@ -0,0 +1,263 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared Lark API error handling utilities.
+ *
+ * Provides unified error handling for two distinct error paths:
+ *
+ * 1. **Response-level errors** — The SDK returns a response object with a
+ *    non-zero `code`.  Handled by {@link assertLarkOk}.
+ *
+ * 2. **Thrown exceptions** — The SDK throws an Axios-style error (HTTP 4xx)
+ *    whose properties include the Feishu error `code` and `msg`.
+ *    Handled by {@link formatLarkError}.
+ *
+ * Adapted from openclaw-lark for MCP Server architecture.
+ */
+// ---------------------------------------------------------------------------
+// Well-known Lark error codes
+// ---------------------------------------------------------------------------
+/**
+ * Well-known Lark API error codes.
+ * @see https://open.feishu.cn/document/ukTMukTMukTM/ugTM5UjL4ETO14COxkTN/code
+ */
+export const LARK_ERROR = {
+    /** Success */
+    SUCCESS: 0,
+    /** Permission denied - app scope missing (tenant level) */
+    APP_SCOPE_MISSING: 99991672,
+    /** User token scope insufficient */
+    USER_SCOPE_INSUFFICIENT: 99991679,
+    /** Invalid access token */
+    INVALID_ACCESS_TOKEN: 99991663,
+    /** Access token expired */
+    ACCESS_TOKEN_EXPIRED: 99991664,
+    /** access_token invalid */
+    TOKEN_INVALID: 99991668,
+    /** access_token expired */
+    TOKEN_EXPIRED: 99991669,
+    /** refresh_token invalid */
+    REFRESH_TOKEN_INVALID: 20003,
+    /** refresh_token expired */
+    REFRESH_TOKEN_EXPIRED: 20004,
+    /** refresh_token missing */
+    REFRESH_TOKEN_MISSING: 20024,
+    /** refresh_token revoked */
+    REFRESH_TOKEN_REVOKED: 20063,
+    /** Message recalled */
+    MESSAGE_RECALLED: 230011,
+    /** Message deleted */
+    MESSAGE_DELETED: 231003,
+};
+// ---------------------------------------------------------------------------
+// Code extraction
+// ---------------------------------------------------------------------------
+/**
+ * Coerce a value to a number if possible.
+ */
+function coerceCode(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+/**
+ * Extract the Lark API code from a thrown error object.
+ *
+ * Supports three common structures:
+ * - `{ code }` — SDK direct mount
+ * - `{ data: { code } }` — Response body nested
+ * - `{ response: { data: { code } } }` — Axios style
+ */
+export function extractLarkApiCode(err) {
+    if (!err || typeof err !== 'object')
+        return undefined;
+    const e = err;
+    return coerceCode(e.code) ?? coerceCode(e.data?.code) ?? coerceCode(e.response?.data?.code);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Assert that a Lark SDK response is successful (code === 0).
+ *
+ * @param res - Lark SDK response object
+ * @throws Error with the message from the response if code is non-zero
+ */
+export function assertLarkOk(res) {
+    if (!res.code || res.code === 0)
+        return;
+    throw new Error(res.msg ?? `Feishu API error (code: ${res.code})`);
+}
+/**
+ * Extract a meaningful error message from a thrown Lark SDK / Axios error.
+ *
+ * The Lark SDK throws Axios errors whose object carries Feishu-specific
+ * fields (`code`, `msg`) alongside the standard `message`. For all errors
+ * we try `err.msg` first (the Feishu detail) and fall back to `err.message`
+ * (the generic Axios text).
+ */
+export function formatLarkError(err) {
+    if (!err || typeof err !== 'object') {
+        return String(err);
+    }
+    const e = err;
+    // Path 1: Lark SDK merges Feishu fields onto the thrown error object.
+    if (typeof e.code === 'number' && e.msg) {
+        return e.msg;
+    }
+    // Path 2: Standard Axios error — dig into response.data.
+    const data = e.response?.data;
+    if (data && typeof data.code === 'number' && data.msg) {
+        return data.msg;
+    }
+    // Fallback.
+    return e.message ?? String(err);
+}
+/**
+ * Check if an error indicates missing app scope/permission.
+ */
+export function isPermissionError(err) {
+    const code = extractLarkApiCode(err);
+    return code === LARK_ERROR.APP_SCOPE_MISSING;
+}
+/**
+ * Check if an error indicates an invalid or expired access token.
+ */
+export function isTokenError(err) {
+    const code = extractLarkApiCode(err);
+    return code === LARK_ERROR.INVALID_ACCESS_TOKEN || code === LARK_ERROR.ACCESS_TOKEN_EXPIRED;
+}
+// ---------------------------------------------------------------------------
+// Error code sets
+// ---------------------------------------------------------------------------
+/** Irrecoverable refresh_token error codes - require re-authorization */
+export const REFRESH_TOKEN_IRRECOVERABLE = new Set([
+    LARK_ERROR.REFRESH_TOKEN_INVALID,
+    LARK_ERROR.REFRESH_TOKEN_EXPIRED,
+    LARK_ERROR.REFRESH_TOKEN_MISSING,
+    LARK_ERROR.REFRESH_TOKEN_REVOKED,
+]);
+/** Message terminal error codes (recalled/deleted) - stop further operations */
+export const MESSAGE_TERMINAL_CODES = new Set([
+    LARK_ERROR.MESSAGE_RECALLED,
+    LARK_ERROR.MESSAGE_DELETED,
+]);
+/** access_token failure error codes - can retry with refresh */
+export const TOKEN_RETRY_CODES = new Set([
+    LARK_ERROR.TOKEN_INVALID,
+    LARK_ERROR.TOKEN_EXPIRED,
+]);
+// ---------------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when no valid UAT exists and the user needs to (re-)authorize.
+ * Callers should catch this and trigger the OAuth flow.
+ */
+export class NeedAuthorizationError extends Error {
+    userOpenId;
+    constructor(userOpenId) {
+        super('need_user_authorization');
+        this.name = 'NeedAuthorizationError';
+        this.userOpenId = userOpenId;
+    }
+}
+/**
+ * Thrown when the app lacks the application:application:self_manage permission.
+ *
+ * The administrator needs to enable this permission in the Lark Developer Console.
+ */
+export class AppScopeCheckFailedError extends Error {
+    appId;
+    constructor(appId) {
+        super('App lacks application:application:self_manage permission. ' +
+            'Please ask the administrator to enable this permission in the Developer Console.');
+        this.name = 'AppScopeCheckFailedError';
+        this.appId = appId;
+    }
+}
+/**
+ * Thrown when the app is missing required OAPI scopes.
+ *
+ * The administrator needs to enable permissions in the Lark Developer Console.
+ */
+export class AppScopeMissingError extends Error {
+    apiName;
+    /** Missing scopes that the app doesn't have */
+    missingScopes;
+    /** All required scopes (including enabled ones), for requesting user authorization after app permission setup */
+    allRequiredScopes;
+    /** Application ID for generating permission management links */
+    appId;
+    scopeNeedType;
+    /** Token type used when this error was triggered */
+    tokenType;
+    constructor(info, scopeNeedType, tokenType, allRequiredScopes) {
+        if (scopeNeedType === 'one') {
+            super(`App missing permission [${info.scopes.join(', ')}] ` +
+                '(enable any one of these). Please ask the administrator to enable in Developer Console.');
+        }
+        else {
+            super(`App missing permission [${info.scopes.join(', ')}]. ` +
+                'Please ask the administrator to enable in Developer Console.');
+        }
+        this.name = 'AppScopeMissingError';
+        this.apiName = info.apiName;
+        this.missingScopes = info.scopes;
+        this.allRequiredScopes = allRequiredScopes;
+        this.appId = info.appId;
+        this.scopeNeedType = scopeNeedType;
+        this.tokenType = tokenType;
+    }
+}
+/**
+ * Thrown when user has not authorized or scope is insufficient.
+ *
+ * `requiredScopes` contains valid scopes from APP∩OAPI intersection,
+ * can be passed directly to OAuth authorize.
+ */
+export class UserAuthRequiredError extends Error {
+    userOpenId;
+    apiName;
+    /** APP∩OAPI intersection scopes, pass to OAuth authorize */
+    requiredScopes;
+    /** Whether app scope was verified. false means requiredScopes may be inaccurate. */
+    appScopeVerified;
+    /** Application ID for generating permission management links */
+    appId;
+    constructor(userOpenId, info) {
+        super('need_user_authorization');
+        this.name = 'UserAuthRequiredError';
+        this.userOpenId = userOpenId;
+        this.apiName = info.apiName;
+        this.requiredScopes = info.scopes;
+        this.appId = info.appId;
+        this.appScopeVerified = info.appScopeVerified ?? true;
+    }
+}
+/**
+ * Thrown when server returns 99991679 - user token scope insufficient.
+ *
+ * Requires incremental authorization: start a new Device Flow with missing scopes.
+ */
+export class UserScopeInsufficientError extends Error {
+    userOpenId;
+    apiName;
+    /** Missing scope list */
+    missingScopes;
+    constructor(userOpenId, info) {
+        super('user_scope_insufficient');
+        this.name = 'UserScopeInsufficientError';
+        this.userOpenId = userOpenId;
+        this.apiName = info.apiName;
+        this.missingScopes = info.scopes;
+    }
+}
+//# sourceMappingURL=api-error.js.map

package/dist/core/api-error.js.map

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

package/dist/core/auth-errors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Authentication error types for cc-lark MCP Server.
+ *
+ * Re-exports error types from api-error.ts for convenience.
+ * This module provides backward compatibility and a dedicated import path.
+ *
+ * Adapted from openclaw-lark for MCP Server architecture.
+ */
+export { LARK_ERROR, REFRESH_TOKEN_IRRECOVERABLE, MESSAGE_TERMINAL_CODES, TOKEN_RETRY_CODES, ScopeErrorInfo, AuthHint, TryInvokeResult, NeedAuthorizationError, AppScopeCheckFailedError, AppScopeMissingError, UserAuthRequiredError, UserScopeInsufficientError, } from './api-error.js';
+//# sourceMappingURL=auth-errors.d.ts.map

package/dist/core/auth-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-errors.d.ts","sourceRoot":"","sources":["../../src/core/auth-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EACL,UAAU,EACV,2BAA2B,EAC3B,sBAAsB,EACtB,iBAAiB,EACjB,cAAc,EACd,QAAQ,EACR,eAAe,EACf,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,gBAAgB,CAAC"}

package/dist/core/auth-errors.js

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Authentication error types for cc-lark MCP Server.
+ *
+ * Re-exports error types from api-error.ts for convenience.
+ * This module provides backward compatibility and a dedicated import path.
+ *
+ * Adapted from openclaw-lark for MCP Server architecture.
+ */
+// Re-export everything from api-error.ts
+export { LARK_ERROR, REFRESH_TOKEN_IRRECOVERABLE, MESSAGE_TERMINAL_CODES, TOKEN_RETRY_CODES, NeedAuthorizationError, AppScopeCheckFailedError, AppScopeMissingError, UserAuthRequiredError, UserScopeInsufficientError, } from './api-error.js';
+//# sourceMappingURL=auth-errors.js.map

package/dist/core/auth-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-errors.js","sourceRoot":"","sources":["../../src/core/auth-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,yCAAyC;AACzC,OAAO,EACL,UAAU,EACV,2BAA2B,EAC3B,sBAAsB,EACtB,iBAAiB,EAIjB,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,gBAAgB,CAAC"}

package/dist/core/config.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Configuration management for the cc-lark MCP Server.
+ *
+ * Loads configuration from environment variables and provides validation.
+ */
+import type { FeishuConfig, ConfigValidationResult, LarkBrand } from './types.js';
+export declare const ENV_VARS: {
+    readonly APP_ID: "FEISHU_APP_ID";
+    readonly APP_SECRET: "FEISHU_APP_SECRET";
+    readonly USER_ACCESS_TOKEN: "FEISHU_USER_ACCESS_TOKEN";
+    readonly BRAND: "FEISHU_BRAND";
+    readonly ENCRYPT_KEY: "FEISHU_ENCRYPT_KEY";
+    readonly VERIFICATION_TOKEN: "FEISHU_VERIFICATION_TOKEN";
+};
+/**
+ * Load Feishu configuration from environment variables.
+ *
+ * Required:
+ * - FEISHU_APP_ID: Feishu App ID
+ * - FEISHU_APP_SECRET: Feishu App Secret
+ *
+ * Optional:
+ * - FEISHU_USER_ACCESS_TOKEN: User access token for user-authorized operations
+ * - FEISHU_BRAND: Platform brand ('feishu' | 'lark' | custom URL)
+ * - FEISHU_ENCRYPT_KEY: Encryption key for webhook events
+ * - FEISHU_VERIFICATION_TOKEN: Verification token for webhooks
+ */
+export declare function loadConfig(): FeishuConfig;
+/**
+ * Validate the Feishu configuration.
+ *
+ * @param config - Configuration to validate
+ * @returns Validation result with errors if any
+ */
+export declare function validateConfig(config: FeishuConfig): ConfigValidationResult;
+/**
+ * Load and validate configuration in one step.
+ *
+ * @throws Error if configuration is invalid
+ * @returns Validated Feishu configuration
+ */
+export declare function loadAndValidateConfig(): FeishuConfig;
+/**
+ * Check if configuration has user access token.
+ *
+ * @param config - Configuration to check
+ * @returns True if user access token is configured
+ */
+export declare function hasUserAccessToken(config: FeishuConfig): boolean;
+/**
+ * Get the base URL for the Lark API based on brand.
+ *
+ * @param brand - Platform brand
+ * @returns Base URL for API calls
+ */
+export declare function getApiBaseUrl(brand?: LarkBrand): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAMlF,eAAO,MAAM,QAAQ;;;;;;;CAOX,CAAC;AAMX;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,IAAI,YAAY,CAgBzC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,sBAAsB,CAyB3E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,YAAY,CASpD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,SAAoB,GAAG,MAAM,CAQjE"}

package/dist/core/config.js

@@ -0,0 +1,115 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Configuration management for the cc-lark MCP Server.
+ *
+ * Loads configuration from environment variables and provides validation.
+ */
+// ---------------------------------------------------------------------------
+// Environment variable names
+// ---------------------------------------------------------------------------
+export const ENV_VARS = {
+    APP_ID: 'FEISHU_APP_ID',
+    APP_SECRET: 'FEISHU_APP_SECRET',
+    USER_ACCESS_TOKEN: 'FEISHU_USER_ACCESS_TOKEN',
+    BRAND: 'FEISHU_BRAND',
+    ENCRYPT_KEY: 'FEISHU_ENCRYPT_KEY',
+    VERIFICATION_TOKEN: 'FEISHU_VERIFICATION_TOKEN',
+};
+// ---------------------------------------------------------------------------
+// Configuration loader
+// ---------------------------------------------------------------------------
+/**
+ * Load Feishu configuration from environment variables.
+ *
+ * Required:
+ * - FEISHU_APP_ID: Feishu App ID
+ * - FEISHU_APP_SECRET: Feishu App Secret
+ *
+ * Optional:
+ * - FEISHU_USER_ACCESS_TOKEN: User access token for user-authorized operations
+ * - FEISHU_BRAND: Platform brand ('feishu' | 'lark' | custom URL)
+ * - FEISHU_ENCRYPT_KEY: Encryption key for webhook events
+ * - FEISHU_VERIFICATION_TOKEN: Verification token for webhooks
+ */
+export function loadConfig() {
+    const appId = process.env[ENV_VARS.APP_ID];
+    const appSecret = process.env[ENV_VARS.APP_SECRET];
+    const userAccessToken = process.env[ENV_VARS.USER_ACCESS_TOKEN];
+    const brand = process.env[ENV_VARS.BRAND];
+    const encryptKey = process.env[ENV_VARS.ENCRYPT_KEY];
+    const verificationToken = process.env[ENV_VARS.VERIFICATION_TOKEN];
+    return {
+        appId: appId ?? '',
+        appSecret: appSecret ?? '',
+        userAccessToken,
+        brand: brand ?? 'feishu',
+        encryptKey,
+        verificationToken,
+    };
+}
+/**
+ * Validate the Feishu configuration.
+ *
+ * @param config - Configuration to validate
+ * @returns Validation result with errors if any
+ */
+export function validateConfig(config) {
+    const errors = [];
+    if (!config.appId) {
+        errors.push(`Missing required environment variable: ${ENV_VARS.APP_ID}`);
+    }
+    if (!config.appSecret) {
+        errors.push(`Missing required environment variable: ${ENV_VARS.APP_SECRET}`);
+    }
+    if (config.brand) {
+        const validBrands = ['feishu', 'lark'];
+        if (!validBrands.includes(config.brand) && !config.brand.startsWith('https://')) {
+            errors.push(`Invalid FEISHU_BRAND value: "${config.brand}". Must be "feishu", "lark", or a custom HTTPS URL`);
+        }
+    }
+    if (errors.length > 0) {
+        return { valid: false, errors };
+    }
+    return { valid: true, errors: [], config };
+}
+/**
+ * Load and validate configuration in one step.
+ *
+ * @throws Error if configuration is invalid
+ * @returns Validated Feishu configuration
+ */
+export function loadAndValidateConfig() {
+    const config = loadConfig();
+    const result = validateConfig(config);
+    if (!result.valid) {
+        throw new Error(`Invalid configuration:\n${result.errors.map(e => `  - ${e}`).join('\n')}`);
+    }
+    return config;
+}
+/**
+ * Check if configuration has user access token.
+ *
+ * @param config - Configuration to check
+ * @returns True if user access token is configured
+ */
+export function hasUserAccessToken(config) {
+    return typeof config.userAccessToken === 'string' && config.userAccessToken.length > 0;
+}
+/**
+ * Get the base URL for the Lark API based on brand.
+ *
+ * @param brand - Platform brand
+ * @returns Base URL for API calls
+ */
+export function getApiBaseUrl(brand = 'feishu') {
+    if (brand === 'lark') {
+        return 'https://open.larksuite.com/open-apis';
+    }
+    if (brand.startsWith('https://')) {
+        return brand;
+    }
+    return 'https://open.feishu.cn/open-apis';
+}
+//# sourceMappingURL=config.js.map

package/dist/core/config.js.map

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

package/dist/core/device-flow.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * OAuth 2.0 Device Authorization Grant (RFC 8628) for Lark/Feishu.
+ *
+ * Two-step flow:
+ *   1. `requestDeviceAuthorization` – obtains device_code + user_code.
+ *   2. `pollDeviceToken` – polls the token endpoint until the user authorizes,
+ *      rejects, or the code expires.
+ *
+ * All HTTP calls use the built-in `fetch` (Node 18+). The Lark SDK is not
+ * used here because these OAuth endpoints are outside the SDK's scope.
+ *
+ * Adapted from openclaw-lark for MCP Server architecture.
+ */
+import type { LarkBrand } from './types.js';
+export interface DeviceAuthResponse {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresIn: number;
+    interval: number;
+}
+export interface DeviceFlowTokenData {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    refreshExpiresIn: number;
+    scope: string;
+}
+export type DeviceFlowResult = {
+    ok: true;
+    token: DeviceFlowTokenData;
+} | {
+    ok: false;
+    error: DeviceFlowError;
+    message: string;
+};
+export type DeviceFlowError = 'authorization_pending' | 'slow_down' | 'access_denied' | 'expired_token';
+/**
+ * Resolve the two OAuth endpoint URLs based on the configured brand.
+ */
+export declare function resolveOAuthEndpoints(brand: LarkBrand): {
+    deviceAuthorization: string;
+    token: string;
+};
+/**
+ * Request a device authorization code from the Feishu OAuth server.
+ *
+ * Uses Confidential Client authentication (HTTP Basic with appId:appSecret).
+ * The `offline_access` scope is automatically appended so that the token
+ * response includes a refresh_token.
+ */
+export declare function requestDeviceAuthorization(params: {
+    appId: string;
+    appSecret: string;
+    brand: LarkBrand;
+    scope?: string;
+}): Promise<DeviceAuthResponse>;
+/**
+ * Poll the token endpoint until the user authorizes, rejects, or the code
+ * expires.
+ *
+ * Handles `authorization_pending` (keep polling), `slow_down` (back off by
+ * +5 s), `access_denied` and `expired_token` (terminal errors).
+ *
+ * Pass an `AbortSignal` to cancel polling from the outside.
+ */
+export declare function pollDeviceToken(params: {
+    appId: string;
+    appSecret: string;
+    brand: LarkBrand;
+    deviceCode: string;
+    interval: number;
+    expiresIn: number;
+    signal?: AbortSignal;
+}): Promise<DeviceFlowResult>;
+//# sourceMappingURL=device-flow.d.ts.map

package/dist/core/device-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-flow.d.ts","sourceRoot":"","sources":["../../src/core/device-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAU5C,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,uBAAuB,EAAE,MAAM,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,GACxC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,MAAM,MAAM,eAAe,GAAG,uBAAuB,GAAG,WAAW,GAAG,eAAe,GAAG,eAAe,CAAC;AAyBxG;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,GAAG;IACvD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf,CA8BA;AAMD;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0D9B;AAoBD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2F5B"}