@hailer/mcp 0.0.1

package/.claude/skills/app-api/references/app-endpoints.md

@@ -0,0 +1,759 @@
+# App API Endpoints Reference
+
+Complete reference for Hailer App API endpoints. Apps are custom web applications that extend Hailer workspace functionality.
+
+## Table of Contents
+
+### Core App Management
+- [v3.app.create](#v3appcreate) - Create new app
+- [v3.app.list](#v3applist) - List all apps in workspace
+- [v3.app.update](#v3appupdate) - Update existing app
+- [v3.app.remove](#v3appremove) - Delete app
+
+### App Permissions
+- [v3.app.member.add](#v3appmemberadd) - Add member permissions
+- [v3.app.member.remove](#v3appmemberremove) - Remove member permissions
+
+### App Configuration
+- [v3.app.config.update](#v3appconfigupdate) - Edit app configuration
+
+### Marketplace Operations
+- [v3.app.product.create](#v3appproductcreate) - Create marketplace product
+- [v3.app.product.get](#v3appproductget) - Get product details
+- [v3.app.product.getManifest](#v3appproductgetmanifest) - Get app manifest
+- [v3.app.product.install](#v3appproductinstall) - Install marketplace app
+- [v3.app.product.getInstalledVersion](#v3appproductgetinstalledversion) - Get installed version
+- [v3.app.product.isProductInstalled](#v3appproductisproductinstalled) - Check installation
+
+---
+
+## Prerequisites
+
+Before using Apps API:
+1. Must have workspace administrator permissions for app creation
+2. Understand difference between app entry (metadata) and app code
+3. For development: Need app scaffolded with `@hailer/create-app`
+4. For publishing: Need app built and manifest configured
+
+---
+
+## v3.app.create
+
+Create new app entry in Hailer workspace.
+
+**Endpoint**: `POST /v3/app/create`
+
+**Request Body**:
+```json
+{
+  "0": {
+    "cid": "workspaceId",         // Optional workspace ID
+    "name": "string",              // App name (required)
+    "description": "string",       // App description
+    "url": "string",               // App URL (empty for published apps)
+    "image": "imageId",            // Optional app icon (24 char ObjectId)
+    "config": {}                   // Optional configuration object
+  }
+}
+```
+
+**Parameters**:
+- `name` (string, required): App display name
+- `description` (string, optional): App description
+- `url` (string, optional): App URL or empty for auto-generated
+- `image` (string, optional): Image/icon ID (24 characters)
+- `config` (object, optional): App configuration
+- `cid` (string, optional): Workspace ID (defaults to current)
+
+**Response** (success):
+```json
+{
+  "code": 0,
+  "msg": "App created successfully",
+  "details": {
+    "appId": "507f1f77bcf86cd799439011"
+  },
+  "debug": null
+}
+```
+
+**Response** (error):
+```json
+{
+  "code": 403,
+  "msg": "Permission denied",
+  "details": {},
+  "debug": null
+}
+```
+
+**Example Usage**:
+
+Development App:
+```javascript
+v3.app.create({
+  name: 'Local Development',
+  description: 'App pointing to local server',
+  url: 'http://localhost:3000'
+})
+```
+
+Published App:
+```javascript
+v3.app.create({
+  name: 'Published App',
+  description: 'Production app',
+  url: '' // Empty for auto URL assignment
+})
+```
+
+**Notes**:
+- Only workspace administrators can create apps
+- URL can be empty (Hailer will assign default publication URL)
+- App icon must be uploaded first to get image ID
+
+---
+
+## v3.app.list
+
+List all apps in the current workspace.
+
+**Endpoint**: `POST /v3/app/list`
+
+**Request Body**:
+```json
+{}
+```
+
+**Parameters**: None (uses current workspace context)
+
+**Response** (success):
+```json
+{
+  "code": 0,
+  "msg": "Apps retrieved successfully",
+  "details": {
+    "apps": [
+      {
+        "_id": "507f1f77bcf86cd799439011",
+        "name": "My App",
+        "description": "Cool app",
+        "url": "http://localhost:3000",
+        "image": "imageId123",
+        "config": {},
+        "created": 1234567890,
+        "updated": 1234567890,
+        "creator": "userId123"
+      }
+    ]
+  },
+  "debug": null
+}
+```
+
+**Response** (error):
+```json
+{
+  "code": 403,
+  "msg": "Permission denied",
+  "details": {},
+  "debug": null
+}
+```
+
+**Example Usage**:
+```javascript
+v3.app.list()
+```
+
+**Notes**:
+- Returns apps user has access to (creator + admins + shared apps)
+- Apps with permissions set may be visible to more users
+- Empty array if no apps exist in workspace
+
+---
+
+## v3.app.update
+
+Update existing app properties.
+
+**Endpoint**: `POST /v3/app/update`
+
+**Request Body**:
+```json
+{
+  "0": "appId",                    // App ID (24 chars)
+  "1": {
+    "cid": "workspaceId",           // Optional workspace ID
+    "name": "string",               // Optional new name
+    "description": "string",        // Optional new description
+    "url": "string",                // Optional new URL
+    "image": "imageId",             // Optional new icon
+    "config": {}                    // Optional new config
+  }
+}
+```
+
+**Parameters**:
+- `appId` (string, required): App ID to update
+- Object with properties to update (all optional):
+  - `name`: New app name
+  - `description`: New description
+  - `url`: New URL
+  - `image`: New image ID
+  - `config`: New configuration
+
+**Response** (success):
+```json
+{
+  "code": 0,
+  "msg": "App updated successfully",
+  "details": {},
+  "debug": null
+}
+```
+
+**Response** (error - not found):
+```json
+{
+  "code": 403,
+  "msg": "App not found",
+  "details": {},
+  "debug": null
+}
+```
+
+**Example Usage**:
+
+Update name and description:
+```javascript
+v3.app.update(
+  '507f1f77bcf86cd799439011',
+  {
+    name: 'Updated App Name',
+    description: 'New description'
+  }
+)
+```
+
+Change URL (switch from dev to prod):
+```javascript
+v3.app.update(
+  '507f1f77bcf86cd799439011',
+  {
+    url: 'https://apps.hailer.com/app/myapp'
+  }
+)
+```
+
+**Notes**:
+- Only app creator or workspace admin can update
+- Only specified properties are updated
+- Empty URL switches to auto-generated publication URL
+
+---
+
+## v3.app.remove
+
+Delete app entry from workspace.
+
+**Endpoint**: `POST /v3/app/remove`
+
+**Request Body**:
+```json
+{
+  "0": "appId"  // App ID (24 characters)
+}
+```
+
+**Parameters**:
+- `appId` (string, required): App ID to remove
+
+**Response** (success):
+```json
+{
+  "code": 0,
+  "msg": "App removed successfully",
+  "details": {},
+  "debug": null
+}
+```
+
+**Response** (error):
+```json
+{
+  "code": 403,
+  "msg": "App not found or permission denied",
+  "details": {},
+  "debug": null
+}
+```
+
+**Example Usage**:
+```javascript
+v3.app.remove('507f1f77bcf86cd799439011')
+```
+
+**Notes**:
+- Only app creator or workspace admin can remove
+- Removes app entry (metadata) only, not the app code
+- Published app code remains on server even after entry removal
+- Permanent operation, cannot be undone
+
+---
+
+## v3.app.member.add
+
+Add member permissions to app (grant access).
+
+**Endpoint**: `POST /v3/app/member/add`
+
+**Request Body**:
+```json
+{
+  "0": "appId",                   // App ID (24 chars)
+  "1": "member"                   // Member identifier
+}
+```
+
+**Parameters**:
+- `appId` (string, required): App ID
+- `member` (string, required): Member identifier in format:
+  - `network_<networkId>` - Entire workspace
+  - `team_<teamId>` - Specific team
+  - `user_<userId>` - Individual user
+  - `group_<groupId>` - Custom group
+
+**Response** (success):
+```json
+{
+  "code": 0,
+  "msg": "Member added successfully",
+  "details": {},
+  "debug": null
+}
+```
+
+**Response** (error):
+```json
+{
+  "code": 403,
+  "msg": "Permission denied or invalid member",
+  "details": {},
+  "debug": null
+}
+```
+
+**Example Usage**:
+
+Share with entire workspace:
+```javascript
+v3.app.member.add(
+  '507f1f77bcf86cd799439011',
+  'network_68446c045b30685f67c6fc8c'
+)
+```
+
+Share with specific team:
+```javascript
+v3.app.member.add(
+  '507f1f77bcf86cd799439011',
+  'team_507f1f77bcf86cd799439012'
+)
+```
+
+Share with individual user:
+```javascript
+v3.app.member.add(
+  '507f1f77bcf86cd799439011',
+  'user_507f1f77bcf86cd799439013'
+)
+```
+
+**Notes**:
+- Only app creator or workspace admin can manage permissions
+- Adding workspace grants access to all workspace members
+- Members can see and use the app once permission granted
+- Duplicate additions are ignored (no error)
+
+---
+
+## v3.app.member.remove
+
+Remove member permissions from app (revoke access).
+
+**Endpoint**: `POST /v3/app/member/remove`
+
+**Request Body**:
+```json
+{
+  "0": "appId",                   // App ID (24 chars)
+  "1": "member"                   // Member identifier
+}
+```
+
+**Parameters**:
+- `appId` (string, required): App ID
+- `member` (string, required): Member identifier (same format as add)
+
+**Response** (success):
+```json
+{
+  "code": 0,
+  "msg": "Member removed successfully",
+  "details": {},
+  "debug": null
+}
+```
+
+**Response** (error):
+```json
+{
+  "code": 403,
+  "msg": "Permission denied",
+  "details": {},
+  "debug": null
+}
+```
+
+**Example Usage**:
+```javascript
+v3.app.member.remove(
+  '507f1f77bcf86cd799439011',
+  'team_507f1f77bcf86cd799439012'
+)
+```
+
+**Notes**:
+- Only app creator or workspace admin can remove permissions
+- Removing workspace revokes access from all workspace members
+- Creator and admins always retain access
+
+---
+
+## v3.app.config.update
+
+Edit app configuration.
+
+**Endpoint**: `POST /v3/app/config/update`
+
+**Request Body**:
+```json
+{
+  "0": "appId",                   // App ID (24 chars)
+  "1": {
+    "fields": {}                   // Configuration fields
+  }
+}
+```
+
+**Parameters**:
+- `appId` (string, required): App ID
+- Configuration object with `fields` property
+
+**Response** (success):
+```json
+{
+  "code": 0,
+  "msg": "Config updated successfully",
+  "details": {},
+  "debug": null
+}
+```
+
+**Example Usage**:
+```javascript
+v3.app.config.update(
+  '507f1f77bcf86cd799439011',
+  {
+    fields: {
+      apiKey: 'secret-key',
+      maxItems: 100
+    }
+  }
+)
+```
+
+**Notes**:
+- Configuration structure depends on app requirements
+- Used for app-specific settings
+- Not exposed in app UI by default
+
+---
+
+## v3.app.product.create
+
+Create marketplace product listing.
+
+**Endpoint**: `POST /v3.app.product.create`
+
+**Request Body**:
+```json
+{
+  "0": {
+    "name": "string"              // Product name
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "Product created",
+  "details": {
+    "productId": "507f1f77bcf86cd799439011"
+  },
+  "debug": null
+}
+```
+
+**Example Usage**:
+```javascript
+v3.app.product.create({
+  name: 'Task Manager Pro'
+})
+```
+
+---
+
+## v3.app.product.get
+
+Get marketplace product details.
+
+**Endpoint**: `POST /v3/app/product/get`
+
+**Request Body**:
+```json
+{
+  "0": "productId"  // Product ID in Hailer market
+}
+```
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "Product retrieved",
+  "details": {
+    "product": {
+      "_id": "productId",
+      "name": "Task Manager Pro",
+      "description": "...",
+      "version": "1.0.0"
+    }
+  },
+  "debug": null
+}
+```
+
+---
+
+## v3.app.product.getManifest
+
+Get app manifest from marketplace product.
+
+**Endpoint**: `POST /v3/app/product/getManifest`
+
+**Request Body**:
+```json
+{
+  "0": "productId"
+}
+```
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "Manifest retrieved",
+  "details": {
+    "manifest": {
+      "name": "Task Manager",
+      "version": "1.0.0",
+      "permissions": []
+    }
+  },
+  "debug": null
+}
+```
+
+---
+
+## v3.app.product.install
+
+Install marketplace app into workspace.
+
+**Endpoint**: `POST /v3/app/product/install`
+
+**Request Body**:
+```json
+{
+  "0": "productId",               // Product ID in market
+  "1": "workspaceId"              // Target workspace
+}
+```
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "App installed successfully",
+  "details": {
+    "appId": "507f1f77bcf86cd799439011"
+  },
+  "debug": null
+}
+```
+
+**Example Usage**:
+```javascript
+v3.app.product.install(
+  'marketProductId123',
+  '68446c045b30685f67c6fc8c'
+)
+```
+
+---
+
+## v3.app.product.getInstalledVersion
+
+Get installed version of marketplace app.
+
+**Endpoint**: `POST /v3/app/product/getInstalledVersion`
+
+**Request Body**:
+```json
+{
+  "0": "productId"
+}
+```
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "Version retrieved",
+  "details": {
+    "version": "1.0.0"
+  },
+  "debug": null
+}
+```
+
+---
+
+## v3.app.product.isProductInstalled
+
+Check if marketplace app is installed in workspace.
+
+**Endpoint**: `POST /v3/app/product/isProductInstalled`
+
+**Request Body**:
+```json
+{
+  "0": "productId",
+  "1": "workspaceId"
+}
+```
+
+**Response**:
+```json
+{
+  "code": 0,
+  "msg": "Check complete",
+  "details": {
+    "installed": true,
+    "appId": "507f1f77bcf86cd799439011"
+  },
+  "debug": null
+}
+```
+
+---
+
+## Common Response Format
+
+All endpoints return this format:
+
+```json
+{
+  "code": 0,        // 0 = success, 403 = error
+  "msg": "string",  // Success/error message
+  "details": {},    // Response data
+  "debug": null     // Optional debug info
+}
+```
+
+---
+
+## Error Handling
+
+**Common Error Codes:**
+- `403` - Permission denied (not admin/creator)
+- `403` - App not found
+- `403` - Invalid member format
+- `403` - Invalid app configuration
+
+**Error Categories:**
+
+**Permission Errors**:
+- User is not app creator or workspace admin
+- User doesn't have access to workspace
+
+**Not Found Errors**:
+- App ID doesn't exist
+- Product ID invalid
+
+**Validation Errors**:
+- Invalid app structure
+- Missing required fields
+- Invalid member format (must be network_*, team_*, user_*, group_*)
+
+---
+
+## Permissions Summary
+
+### Can Manage Apps:
+✅ Workspace administrators
+✅ App creators
+
+### Can Use Apps:
+✅ Creator
+✅ Workspace administrators
+✅ Members with explicit permissions
+
+---
+
+## Development Workflow
+
+1. **Create Dev App Entry** → `v3.app.create` with localhost URL
+2. **Scaffold App** → `npm create @hailer/app@latest`
+3. **Develop Locally** → `npm run dev`
+4. **Create Prod App Entry** → `v3.app.create` with empty URL
+5. **Configure Manifest** → Set appId in manifest.json
+6. **Publish** → `npm run publish-production`
+7. **Manage Permissions** → `v3.app.member.add` to share
+
+---
+
+## Best Practices
+
+1. **Use descriptive names** - Clear app names help users identify purpose
+2. **Set descriptions** - Explain what the app does
+3. **Manage permissions carefully** - Don't over-share sensitive apps
+4. **Use dev apps for development** - Keep localhost apps separate from production
+5. **Empty URL for production** - Let Hailer manage production URLs
+6. **Version your apps** - Track changes in manifest.json
+7. **Test before publishing** - Always test in dev app first
+
+---
+
+## Next Steps
+
+When building App MCP tools:
+1. **Check permissions**: Verify user is admin or creator
+2. **Handle both app types**: Support dev (with URL) and prod (empty URL)
+3. **Member management**: Support all member formats (network, team, user, group)
+4. **Clear feedback**: Show app ID, URL, and permissions
+5. **Error handling**: Handle permission, not found, and validation errors