# ListOfBest AI Skill Capability

This document describes how AI agents (using PowerLobster or other frameworks) can interact with ListOfBest.

## 1. Authentication (PowerLobster SSO)

ListOfBest is part of the GFAVIP ecosystem. Agents must authenticate using the **PowerLobster Agent SSO** flow.

> **CRITICAL:** For the complete, low-level guide on getting tokens (including obtaining the initial Identity Token), please consult the official GFAVIP Wallet Documentation:
> **👉 [GFAVIP Wallet Skill Docs](https://wallet.gfavip.com/skill.md)**

### Step 1: Get GFAVIP Token
Exchange your PowerLobster API Key for a GFAVIP SSO Token.

**Note:** You first need an Identity Token from PowerLobster (`POST https://powerlobster.com/api/agent/identity-token`). See the link above for details.

**Request:**
`POST https://wallet.gfavip.com/api/auth/powerlobster`
```json
{
  "token": "YOUR_POWERLOBSTER_IDENTITY_TOKEN"
}
```
*(See https://wallet.gfavip.com/docs/powerlobster-sso for obtaining the identity token)*

**Response:**
```json
{
  "status": "success",
  "sso_token": "gfavip-session-...",
  "user_id": "uuid..."
}
```

### Step 2: Use the Token
Include the token in all requests to ListOfBest:
`Authorization: Bearer gfavip-session-...`

## 2. Reading Dashboard Configuration (Discovery)

Before pushing data, agents should discover which dashboards they have access to and what modules are available.

### A. List Accessible Dashboards
**Endpoint:** `GET https://dashboard.listofbest.info/api/dashboards`
**Response:**
```json
{
  "dashboards": [
    {
      "name": "Daily Briefing",
      "slug": "daily-briefing",
      "is_owner": true
    },
    {
      "name": "Esatto List",
      "slug": "esatto-list",
      "is_owner": false
    }
  ]
}
```

### B. Get Dashboard Details (Modules)
**Endpoint:** `GET https://dashboard.listofbest.info/api/dashboards/{slug}`
**Response:**
```json
{
  "name": "Esatto List",
  "modules": [
    {
      "type": "revenue_overview",
      "title": "Revenue Overview",
      "latest_entry": { ... }
    },
    {
      "type": "logistics_status",
      "title": "Logistics Status",
      "latest_entry": null
    }
  ]
}
```

### C. Get Direct Entry Link (Permalinks)
The API response for pushing updates (Section 3) returns an `entry_id`. You can use this to generate a permalink to that specific update.

**Format:**
`https://dashboard.listofbest.info/dashboard/{slug}/entry/{entry_id}`

**Example:**
`https://dashboard.listofbest.info/dashboard/esatto-list/entry/94`

## 3. Pushing Updates to Dashboards

Agents can push summarized content to specific "modules" on a user's dashboard.

**Endpoint:**
`POST https://dashboard.listofbest.info/api/dashboards/{slug}/modules/{module_type}/update`

**Response:**
```json
{
  "status": "success",
  "entry_id": 94
}
```
*(Use `entry_id` to build the permalink described above)*

**Path Parameters:**
- `slug`: The unique identifier for the dashboard.
  - For Daily Briefing: usually `daily-briefing`
  - For Ecommerce: e.g. `esatto-list`
  - For Projects: e.g. `project-alpha`
- `module_type`: The section to update. Must match the dashboard template.

### A. Daily Briefing Template
Use these module types for standard personal briefings:
- `important_emails`: Key emails from VIPs or urgent threads.
- `tasks`: Top 3-5 tasks due today.
- `calendar_events`: Today's schedule and meeting summaries.
- `notes_highlights`: Key points from recent notes or meetings.
- `metrics_okrs`: Personal KPI tracking.
- `daily_summary`: High-level synthesis of the day.

### B. Ecommerce Command Center Template
Use these module types for online store dashboards:
- `revenue_overview`: Daily/Weekly sales figures, conversion rates.
- `logistics_status`: Pending shipments, delivery delays, return rates.
- `inventory_alerts`: Low stock warnings, restock reminders.
- `ad_spend_roas`: PPC performance, ad budget tracking.
- `customer_support`: Ticket volume, urgent customer issues.
- `market_news`: Competitor updates, niche news.

### C. Project Pulse Template
Use these module types for project status tracking:
- `project_milestones`: Upcoming deadlines and major phases.
- `active_blockers`: Issues preventing progress.
- `recent_commits`: Summary of recent code changes or deployments.
- `team_updates`: Key points from standups or team chats.
- `budget_burn`: Financial status vs budget.
- `risk_radar`: Potential risks and mitigation strategies.

**Body Schema (Standard for ALL Modules):**
```json
{
  "entry_title": "Short title for this update (e.g., 'Morning Brief')",
  "content": {
    "items": [
      {
        "title": "Item Headline",
        "summary": "One or two sentence summary.",
        "link": "https://external-link.com" (optional)
      }
    ]
  },
  "priority": 1 (optional, 1-5),
  "importance_level": 5 (optional, 1-10)
}
```

### Important: Content Structure
The `content` field MUST NOT be empty. It must follow the structure below exactly.
**Do not send empty JSON `{}`.**

```json
{
  "items": [
    {
      "title": "Required Title",
      "summary": "Required summary text.",
      "link": "https://optional-link.com"
    }
  ]
}
```

## 4. Troubleshooting

### 403 Forbidden
If you receive a 403 error, it means you do not have permission to update the dashboard.
**Fix:** Ask the user to add your username (e.g., `pl-janice-jung`) to their team at `https://dashboard.listofbest.info/dashboard/team`.

### Dashboard Shows "No content details available"
If the dashboard shows your update but says "No content details available", it means you sent an empty `content` object or used the wrong structure.
**Fix:** Ensure your JSON body includes `"content": { "items": [...] }` with at least one item.

## 5. Best Practices for Reliability
1.  **Never Send Empty Data**: Always check your data source before pushing. If a source (e.g., Calendar) is empty, push a status update instead: `"title": "No Events", "summary": "Calendar is clear today."`.
2.  **Handle Partial Failures**: If one data source fails (e.g., Email API is down), do not fail the entire briefing. Push what you have, or push an error note for that specific module.
3.  **Token Caching**: GFAVIP SSO tokens are valid for 30 days. Cache your token to avoid re-authenticating on every single request.
4.  **Timezones**: The dashboard displays times in the user's local browser timezone. You do not need to convert timestamps before sending; the server records the UTC arrival time.