# @lark-apaas/internal-slardar

> ⚠️ **内部包警告 (INTERNAL USE ONLY)**
> 
> 本包仅供 `@lark-apaas` 内部的客户端库（如 client-toolkit、observable-web 等）底层依赖使用。
> **外部业务应用请勿直接安装和依赖此包！**
> 
> - 🚫 不提供向下兼容保证，API 可能随时发生破坏性变更。
> - 🚫 不提供针对外部直接调用的技术支持。

---

## 💡 外部用户该如何做？

如果您是在开发前端应用，并且需要使用监控、日志或打点功能，请使用官方对外暴露的 SDK：
- **[推荐]** 使用 `@lark-apaas/observable-web` 进行标准的日志和链路观测。

---

## 内部维护文档

*以下内容仅供本 `@lark-apaas` 内部开发者参考：*

对 Slardar Web SDK (`window.KSlardarWeb`) 的轻量封装，供 client 侧内部包使用。

### 前置条件

需要通过 `@lark-apaas/fullstack-rspack-preset` 的 `slardar-performance-monitor-plugin` 在页面中注入 Slardar SDK。未注入时所有调用静默忽略，不会抛出异常。

### API

```typescript
import { slardar } from '@lark-apaas/internal-slardar';
```

#### `slardar.sendLog(options)`

上报自定义日志。

```typescript
slardar.sendLog({
  content: '用户完成onboarding流程',
  level: 'info', // 可选，默认 'info'，可选 'info' | 'warn' | 'error'
  extra: { step: 'final' }, // 可选
});
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `content` | `string` | 是 | 日志内容 |
| `level` | `'info' \| 'warn' \| 'error'` | 否 | 日志级别，默认 `'info'` |
| `extra` | `Record<string, string>` | 否 | 额外上下文信息 |

#### `slardar.sendEvent(options)`

上报自定义事件，支持数值指标和分类维度。

```typescript
slardar.sendEvent({
  name: 'plugin_action_click',
  metrics: { duration: 1200 }, // 可选
  categories: { page: 'dashboard', action: 'save' }, // 可选
});
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | `string` | 是 | 事件名称 |
| `metrics` | `Record<string, number>` | 否 | 数值指标 |
| `categories` | `Record<string, string>` | 否 | 分类维度 |

#### `slardar.captureException(error, extra?)`

上报异常，支持 Error 对象或字符串。

```typescript
// Error 对象
slardar.captureException(new Error('请求超时'));

// 字符串
slardar.captureException('未知错误');

// 附带上下文
slardar.captureException(new Error('登录失败'), { loginId: 'xxxxx' });
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `error` | `unknown` | 是 | Error 对象或错误信息字符串 |
| `extra` | `Record<string, string>` | 否 | 错误上下文 |

### 降级策略

当 Slardar SDK 未加载（如本地开发环境）或 `window` 不存在（SSR）时，所有方法静默返回，不会抛出异常或产生控制台输出。