@1aboveio/skills 0.10.0

package/skills/fullstack/better-auth/references/feishu-api.md

@@ -0,0 +1,270 @@
+# Feishu OAuth API Reference
+
+Load this file when implementing Feishu OAuth or troubleshooting auth issues.
+
+## OAuth Flow Endpoints
+
+### Authorization
+
+```
+GET https://accounts.feishu.cn/open-apis/authen/v1/authorize
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `client_id` | Yes | Feishu App ID (`cli_xxx`) |
+| `redirect_uri` | Yes | Must match registered URI exactly |
+| `response_type` | Yes | Always `code` |
+| `state` | Yes | CSRF token (managed by Better Auth) |
+| `scope` | No | Space-separated scopes |
+
+### Token Exchange
+
+```
+POST https://open.feishu.cn/open-apis/authen/v2/oauth/token
+Content-Type: application/json
+```
+
+**Request body:**
+```json
+{
+  "grant_type": "authorization_code",
+  "code": "<auth_code>",
+  "client_id": "cli_xxx",
+  "client_secret": "xxx"
+}
+```
+
+**Response:**
+```json
+{
+  "access_token": "u-xxxxxxxx",
+  "token_type": "Bearer",
+  "expires_in": 7200,
+  "refresh_token": "ur-xxxxxxxx",
+  "refresh_expires_in": 2592000
+}
+```
+
+> Note: v2 token endpoint returns flat JSON (no `data` wrapper). v1 used `data` wrapper.
+
+### User Info
+
+```
+GET https://open.feishu.cn/open-apis/authen/v1/user_info
+Authorization: Bearer <access_token>
+```
+
+**Response:**
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "open_id": "ou_xxxxxxxxxxxxxxxxxxxxxxxx",
+    "union_id": "on_xxxxxxxxxxxxxxxxxxxxxxxx",
+    "name": "张三",
+    "en_name": "John Zhang",
+    "email": "john@company.com",
+    "avatar_url": "https://internal-api-lark-file.feishu.cn/...",
+    "tenant_key": "xxxxxxxx",
+    "employee_no": ""
+  }
+}
+```
+
+> ⚠️ User data is nested under `data` — must unwrap once. Do NOT double-unwrap.
+
+### 1. Authorization (redirect user)
+
+```
+GET https://accounts.feishu.cn/open-apis/authen/v1/authorize
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `client_id` | Yes | Feishu App ID (`cli_xxx`) |
+| `redirect_uri` | Yes | Must match registered URI exactly |
+| `response_type` | Yes | Always `code` |
+| `state` | Yes | CSRF token (managed by Better Auth) |
+| `scope` | No | Space-separated scopes |
+
+### 2. Token Exchange
+
+```
+POST https://open.feishu.cn/open-apis/authen/v2/oauth/token
+Content-Type: application/json
+```
+
+**Request body:**
+```json
+{
+  "grant_type": "authorization_code",
+  "code": "<auth_code>",
+  "client_id": "cli_xxx",
+  "client_secret": "xxx"
+}
+```
+
+**Response:**
+```json
+{
+  "access_token": "u-xxxxxxxx",
+  "token_type": "Bearer",
+  "expires_in": 7200,
+  "refresh_token": "ur-xxxxxxxx",
+  "refresh_expires_in": 2592000
+}
+```
+
+> Note: v2 token endpoint returns flat JSON (no `data` wrapper). v1 used `data` wrapper.
+
+### 3. User Info
+
+```
+GET https://open.feishu.cn/open-apis/authen/v1/user_info
+Authorization: Bearer <access_token>
+```
+
+**Response:**
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "open_id": "ou_xxxxxxxxxxxxxxxxxxxxxxxx",
+    "union_id": "on_xxxxxxxxxxxxxxxxxxxxxxxx",
+    "name": "张三",
+    "en_name": "John Zhang",
+    "email": "john@company.com",
+    "avatar_url": "https://internal-api-lark-file.feishu.cn/...",
+    "tenant_key": "xxxxxxxx",
+    "employee_no": ""
+  }
+}
+```
+
+> ⚠️ User data is nested under `data` — must unwrap once. Do NOT double-unwrap.
+
+## User Info Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `open_id` | string | Unique per user per app — changes if app changes |
+| `union_id` | string | Unique per user across same developer's apps |
+| `name` | string | Display name (often Chinese) |
+| `en_name` | string | English name (may be empty) |
+| `email` | string | **Empty string if scope not approved** (not null, not omitted) |
+| `avatar_url` | string | Profile picture |
+| `tenant_key` | string | Organization identifier |
+| `employee_no` | string | Employee number (if configured) |
+
+## Scopes & Permissions
+
+| Scope | Level | Admin Approval |
+|-------|-------|----------------|
+| (none — basic profile) | Basic | Auto |
+| `contact:user.email:readonly` | Advanced (高级权限) | **Required** |
+| `contact:user.phone:readonly` | Advanced | **Required** |
+| `contact:user.employee_id:readonly` | Advanced | **Required** |
+
+### Activating Advanced Permissions
+
+1. Open app in [Feishu Dev Console](https://open.feishu.cn/app)
+2. Permissions → find the scope → **Enable**
+3. App Release → **Create Version** → **Submit for Review**
+4. Admin approves in Admin Console
+5. Permission status changes to **Active**
+
+Until approved: the field returns empty string `""`.
+
+## Error Codes
+
+| Code | Meaning | Fix |
+|------|---------|-----|
+| 0 | Success | — |
+| 10003 | Invalid app_id | Check credentials |
+| 10012 | App not released | Publish a version |
+| 10014 | Scope not approved | Request admin approval |
+| 20028 | Invalid code / expired | Code was reused or expired (10 min TTL) |
+| 20029 | Redirect URI mismatch | Add exact URL in Feishu app settings |
+
+## Prisma Schema
+
+Better Auth with genericOAuth requires these models:
+
+```prisma
+model User {
+  id            String    @id @default(cuid())
+  name          String?
+  email         String?   @unique
+  emailVerified Boolean   @default(false) @map("email_verified")
+  image         String?
+  createdAt     DateTime  @default(now()) @map("created_at")
+  updatedAt     DateTime  @updatedAt @map("updated_at")
+  sessions      Session[]
+  accounts      Account[]
+  @@map("users")
+}
+
+model Session {
+  id        String   @id @default(cuid())
+  expiresAt DateTime @map("expires_at")
+  token     String   @unique @default(cuid())
+  ipAddress String?  @map("ip_address")
+  userAgent String?  @map("user_agent")
+  userId    String   @map("user_id")
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+  @@map("sessions")
+}
+
+model Account {
+  id                    String    @id @default(cuid())
+  userId                String    @map("user_id")
+  accountId             String    @map("account_id")
+  providerId            String    @map("provider_id")
+  accessToken           String?   @map("access_token")
+  refreshToken          String?   @map("refresh_token")
+  idToken               String?   @map("id_token")
+  accessTokenExpiresAt  DateTime? @map("access_token_expires_at")
+  refreshTokenExpiresAt DateTime? @map("refresh_token_expires_at")
+  scope                 String?
+  password              String?
+  user                  User      @relation(fields: [userId], references: [id], onDelete: Cascade)
+  createdAt             DateTime  @default(now()) @map("created_at")
+  updatedAt             DateTime  @updatedAt @map("updated_at")
+  @@unique([providerId, accountId])
+  @@map("accounts")
+}
+
+// Required by genericOAuth plugin for CSRF state
+model Verification {
+  id         String   @id @default(cuid())
+  identifier String
+  value      String
+  expiresAt  DateTime @map("expires_at")
+  createdAt  DateTime @default(now()) @map("created_at")
+  updatedAt  DateTime @updatedAt @map("updated_at")
+  @@map("verification")
+}
+```
+
+### Schema Gotchas
+
+- **`emailVerified` must be `Boolean`**, not `DateTime` — Better Auth writes `true`/`false`, not timestamps
+- **Account columns need `At` suffix** — `accessTokenExpiresAt` / `refreshTokenExpiresAt` (Prisma adapter uses camelCase field names)
+- **`@map()` for snake_case columns** — Prisma field names are camelCase; use `@map` for DB column names
+- **`verification` table is mandatory** — genericOAuth stores OAuth state here; missing table = 500 on sign-in
+
+## International (Lark) vs China (Feishu)
+
+| | China | International |
+|---|-------|---------------|
+| Base domain | `feishu.cn` | `larksuite.com` |
+| Auth URL | `accounts.feishu.cn` | `accounts.larksuite.com` |
+| API URL | `open.feishu.cn` | `open.larksuite.com` |
+| Dev Console | `open.feishu.cn/app` | `open.larksuite.com/app` |
+
+Use `FEISHU_BASE_URL` env var to switch between them.

package/skills/fullstack/monorepo/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO