Refactor channel management documentation and update database schema

- Updated documentation for channel API endpoints in Japanese, Korean, and Chinese to improve clarity and consistency.
- Enhanced channel operations section to include detailed request and response formats, including error handling.
- Revised database schema to include new fields for device restrictions and channel configurations.
- Modified Supabase types to reflect changes in the database schema, adding support for device-specific settings.

Author: riderx

src/content/docs/de/docs/plugins/updater/self-hosted/handling-channels.mdx

@@ -14,7 +14,7 @@ Channels are a core mechanism for managing app updates in Capgo. In self-hosted
 
 Channels allow you to:
 - **Control update distribution**: Assign different app versions to different user groups
-- **A/B testing**: Test new features with specific user segments  
+- **A/B testing**: Test new features with specific user segments
 - **Staged rollouts**: Gradually deploy updates to minimize risk
 - **Environment separation**: Separate development, staging, and production updates
 
@@ -36,9 +36,9 @@ Configure the channel endpoint URL in your `capacitor.config.json`:
 
 The plugin performs different channel operations that your endpoint needs to handle:
 
-### 1. Get Channel (GET Request)
+### 1. List Compatible Channels (GET Request)
 
-When the plugin calls `getChannel()`, it sends a GET request to retrieve the device's current channel assignment.
+When the plugin calls `listChannels()`, it sends a GET request to retrieve all channels that are compatible with the device. This returns channels that match the device's environment (dev/prod, emulator/real device) and allow either public access or self-assignment.
 
 #### Request Format
 ```typescript
@@ -48,7 +48,59 @@ When the plugin calls `getChannel()`, it sends a GET request to retrieve the dev
   "Content-Type": "application/json"
 }
 
-// Query parameters or body:
+// Query parameters:
+interface ListChannelsRequest {
+  app_id: string
+  platform: "ios" | "android"
+  is_emulator: boolean
+  is_prod: boolean
+  key_id?: string
+}
+```
+
+#### Response Format
+```json
+[
+  {
+    "id": 1,
+    "name": "production",
+    "public": true,
+    "allow_self_set": false
+  },
+  {
+    "id": 2,
+    "name": "beta",
+    "public": false,
+    "allow_self_set": true
+  }
+]
+```
+
+#### Understanding Channel Types
+
+The response includes two important flags for each channel:
+
+- **`public: true`**: This is a **default channel**. Devices cannot self-assign to it using `setChannel()`. Instead, if a device removes its channel assignment (using `unsetChannel()`), it will automatically receive updates from this public channel if it matches the device's conditions.
+
+- **`allow_self_set: true`**: This is a **self-assignable channel**. Devices can explicitly assign themselves to this channel using `setChannel()`. This is useful for beta testing, A/B testing, or allowing users to opt-in to specific update tracks.
+
+:::note
+A channel can be either `public` OR `allow_self_set`, but typically not both. Public channels serve as the default fallback, while self-assignable channels require explicit opt-in.
+:::
+
+### 2. Get Channel (PUT Request)
+
+When the plugin calls `getChannel()`, it sends a PUT request to retrieve the device's current channel assignment.
+
+#### Request Format
+```typescript
+// PUT /api/channel_self
+// Headers:
+{
+  "Content-Type": "application/json"
+}
+
+// Body:
 interface GetChannelRequest {
   device_id: string
   app_id: string
@@ -57,6 +109,10 @@ interface GetChannelRequest {
   version_build: string
   version_code: string
   version_name: string
+  is_emulator: boolean
+  is_prod: boolean
+  defaultChannel?: string
+  channel?: string  // For newer plugin versions, contains local channel override
 }
 ```
 
@@ -71,7 +127,7 @@ interface GetChannelRequest {
 }
 ```
 
-### 2. Set Channel (POST Request)
+### 3. Set Channel (POST Request)
 
 When the plugin calls `setChannel()`, it sends a POST request to assign the device to a specific channel.
 
@@ -87,6 +143,8 @@ interface SetChannelRequest {
   version_build: string
   version_code: string
   version_name: string
+  is_emulator: boolean
+  is_prod: boolean
 }
 ```
 
@@ -99,7 +157,29 @@ interface SetChannelRequest {
 }
 ```
 
-### 3. Unset Channel (DELETE Request)
+#### Error Cases
+
+When a device tries to assign itself to a **public channel** (one with `public: true`), your endpoint should return an error:
+
+```json
+{
+  "status": "error",
+  "error": "public_channel_self_set_not_allowed",
+  "message": "This channel is public and does not allow device self-assignment. Unset the channel and the device will automatically use the public channel."
+}
+```
+
+When a device tries to assign itself to a channel that doesn't allow self-assignment:
+
+```json
+{
+  "status": "error",
+  "error": "channel_self_set_not_allowed",
+  "message": "This channel does not allow devices to self associate"
+}
+```
+
+### 4. Unset Channel (DELETE Request)
 
 When the plugin calls `unsetChannel()`, it sends a DELETE request to remove the device's channel assignment.
 
@@ -144,20 +224,20 @@ interface ChannelResponse {
 export const handler = async (event) => {
   const method = event.httpMethod || event.method
   const body = JSON.parse(event.body || '{}') as ChannelRequest
-  
+
   const { device_id, app_id, channel, platform } = body
 
   try {
     switch (method) {
       case 'GET':
         return await getDeviceChannel(device_id, app_id)
-        
+
       case 'POST':
         return await setDeviceChannel(device_id, app_id, channel!, platform)
-        
+
       case 'DELETE':
         return await unsetDeviceChannel(device_id, app_id)
-        
+
       default:
         return {
           status: "error",
@@ -175,15 +255,15 @@ export const handler = async (event) => {
 async function getDeviceChannel(deviceId: string, appId: string): Promise<ChannelResponse> {
   // Query your database for device channel assignment
   const assignment = await database.getDeviceChannel(deviceId, appId)
-  
+
   if (assignment) {
     return {
       status: "ok",
       channel: assignment.channel,
       allowSet: assignment.allowSelfAssign
     }
   }
-  
+
   // Return default channel if no assignment found
   return {
     status: "ok",
@@ -193,46 +273,46 @@ async function getDeviceChannel(deviceId: string, appId: string): Promise<Channe
 }
 
 async function setDeviceChannel(
-  deviceId: string, 
-  appId: string, 
-  channel: string, 
+  deviceId: string,
+  appId: string,
+  channel: string,
   platform: string
 ): Promise<ChannelResponse> {
   // Validate channel exists and allows self-assignment
   const channelConfig = await database.getChannelConfig(channel, appId)
-  
+
   if (!channelConfig) {
     return {
       status: "error",
       error: "Channel not found"
     }
   }
-  
+
   if (!channelConfig.allowDeviceSelfSet) {
     return {
       status: "error",
       error: "Channel does not allow self-assignment"
     }
   }
-  
+
   // Check platform restrictions
   if (platform === "ios" && !channelConfig.ios) {
     return {
-      status: "error", 
+      status: "error",
       error: "Channel not available for iOS"
     }
   }
-  
+
   if (platform === "android" && !channelConfig.android) {
     return {
       status: "error",
-      error: "Channel not available for Android" 
+      error: "Channel not available for Android"
     }
   }
-  
+
   // Save the assignment
   await database.setDeviceChannel(deviceId, appId, channel)
-  
+
   return {
     status: "ok",
     message: "Device assigned to channel successfully"
@@ -242,7 +322,7 @@ async function setDeviceChannel(
 async function unsetDeviceChannel(deviceId: string, appId: string): Promise<ChannelResponse> {
   // Remove device channel assignment
   await database.removeDeviceChannel(deviceId, appId)
-  
+
   return {
     status: "ok",
     message: "Device channel assignment removed"
@@ -258,22 +338,67 @@ Your channel system should support these configuration options:
 interface ChannelConfig {
   name: string
   appId: string
-  
+
   // Platform targeting
-  ios: boolean
-  android: boolean
-  
-  // Device restrictions
-  allowDeviceSelfSet: boolean  // Allow setChannel() calls
-  allowEmulator: boolean
-  allowDev: boolean           // Allow development builds
-  
+  ios: boolean              // Allow updates to iOS devices
+  android: boolean          // Allow updates to Android devices
+
+  // Device type restrictions
+  allow_emulator: boolean   // Allow updates on emulator/simulator devices
+  allow_device: boolean     // Allow updates on real/physical devices
+
+  // Build type restrictions
+  allow_dev: boolean        // Allow updates on development builds (is_prod=false)
+  allow_prod: boolean       // Allow updates on production builds (is_prod=true)
+
+  // Channel assignment
+  public: boolean           // Default channel - devices fall back to this when no override
+  allowDeviceSelfSet: boolean  // Allow devices to self-assign via setChannel()
+
   // Update policies
   disableAutoUpdate: "major" | "minor" | "version_number" | "none"
   disableAutoUpdateUnderNative: boolean
-  
-  // Assignment
-  isDefault: boolean          // Default channel for new devices
+}
+```
+
+### Device Filtering Logic
+
+When listing compatible channels (GET request), you should filter channels based on these conditions:
+
+1. **Platform check**: Channel must allow the device's platform (`ios` or `android`)
+2. **Device type check**:
+   - If `is_emulator=true`: Channel must have `allow_emulator=true`
+   - If `is_emulator=false`: Channel must have `allow_device=true`
+3. **Build type check**:
+   - If `is_prod=true`: Channel must have `allow_prod=true`
+   - If `is_prod=false`: Channel must have `allow_dev=true`
+4. **Visibility check**: Channel must be either `public=true` OR `allow_device_self_set=true`
+
+```typescript
+// Example filtering logic
+function getCompatibleChannels(
+  platform: 'ios' | 'android',
+  isEmulator: boolean,
+  isProd: boolean,
+  channels: ChannelConfig[]
+): ChannelConfig[] {
+  return channels.filter(channel => {
+    // Platform check
+    if (!channel[platform]) return false
+
+    // Device type check
+    if (isEmulator && !channel.allow_emulator) return false
+    if (!isEmulator && !channel.allow_device) return false
+
+    // Build type check
+    if (isProd && !channel.allow_prod) return false
+    if (!isProd && !channel.allow_dev) return false
+
+    // Must be accessible (public or self-assignable)
+    if (!channel.public && !channel.allowDeviceSelfSet) return false
+
+    return true
+  })
 }
 ```
 
@@ -287,23 +412,36 @@ CREATE TABLE channels (
   id SERIAL PRIMARY KEY,
   name VARCHAR(255) NOT NULL,
   app_id VARCHAR(255) NOT NULL,
+
+  -- Platform targeting
   ios BOOLEAN DEFAULT true,
   android BOOLEAN DEFAULT true,
-  allow_device_self_set BOOLEAN DEFAULT false,
-  allow_emulator BOOLEAN DEFAULT true,
-  allow_dev BOOLEAN DEFAULT true,
+
+  -- Device type restrictions
+  allow_emulator BOOLEAN DEFAULT true,   -- Allow emulator/simulator devices
+  allow_device BOOLEAN DEFAULT true,     -- Allow real/physical devices
+
+  -- Build type restrictions
+  allow_dev BOOLEAN DEFAULT true,        -- Allow development builds
+  allow_prod BOOLEAN DEFAULT true,       -- Allow production builds
+
+  -- Channel assignment
+  public BOOLEAN DEFAULT false,          -- Default channel (fallback)
+  allow_device_self_set BOOLEAN DEFAULT false,  -- Allow self-assignment
+
+  -- Update policies
   disable_auto_update VARCHAR(50) DEFAULT 'none',
   disable_auto_update_under_native BOOLEAN DEFAULT false,
-  is_default BOOLEAN DEFAULT false,
+
   created_at TIMESTAMP DEFAULT NOW(),
   UNIQUE(name, app_id)
 );
 
--- Device channel assignments table  
+-- Device channel assignments table
 CREATE TABLE device_channels (
   id SERIAL PRIMARY KEY,
   device_id VARCHAR(255) NOT NULL,
-  app_id VARCHAR(255) NOT NULL, 
+  app_id VARCHAR(255) NOT NULL,
   channel_name VARCHAR(255) NOT NULL,
   assigned_at TIMESTAMP DEFAULT NOW(),
   UNIQUE(device_id, app_id)
@@ -323,7 +461,7 @@ Handle common error scenarios:
 
 // Self-assignment not allowed
 {
-  "status": "error", 
+  "status": "error",
   "error": "Channel does not allow device self-assignment"
 }
 
@@ -357,10 +495,10 @@ async function getUpdateForDevice(deviceId: string, appId: string) {
   // Get device's channel assignment
   const channelAssignment = await getDeviceChannel(deviceId, appId)
   const channel = channelAssignment.channel || 'production'
-  
+
   // Get the version assigned to this channel
   const channelVersion = await getChannelVersion(channel, appId)
-  
+
   return {
     version: channelVersion.version,
     url: channelVersion.url,