npm package: @leiyangyou/wechaty-puppet-gateway
Description: Generic gRPC gateway for Wechaty puppets - run any puppet as a remote service
Latest version: 0.1.0

# wechaty-puppet-gateway

Generic gRPC gateway for Wechaty puppets. Run any Wechaty puppet as a remote service.

## Architecture

```
┌─────────────────────────────────────┐     ┌─────────────────────────────────────┐
│      Machine A (Gateway)            │     │      Machine B (Your App)           │
│                                     │     │                                     │
│  ┌─────────────────────────────┐    │     │    ┌─────────────────────────┐      │
│  │ Real Puppet                 │    │     │    │   Your Wechaty App      │      │
│  │ (@wechatferry/puppet, etc.) │    │     │    │   (moltbot, etc.)       │      │
│  └─────────────┬───────────────┘    │     │    └───────────┬─────────────┘      │
│                │                    │     │                │                    │
│                ▼                    │     │                ▼                    │
│  ┌─────────────────────────────┐    │     │    ┌─────────────────────────┐      │
│  │  wechaty-puppet-gateway     │◀───┼─────┼────│ @juzi/wechaty-puppet-   │      │
│  │  (this package)             │    │     │    │ service (client)        │      │
│  │  gRPC server on :8788       │    │     │    │ endpoint: machineA:8788 │      │
│  └─────────────────────────────┘    │     │    └─────────────────────────┘      │
│                                     │     │                                     │
└─────────────────────────────────────┘     └─────────────────────────────────────┘
```

## Quick Start

```bash
# Run with any puppet (auto-installs if missing)
npx wechaty-puppet-gateway --puppet @wechatferry/puppet

# Or with a config file
npx wechaty-puppet-gateway --config ./config.json
```

## Installation

```bash
npm install -g wechaty-puppet-gateway

# Or run directly with npx (recommended)
npx wechaty-puppet-gateway --puppet <puppet-name>
```

## Usage

### CLI Options

```
Usage: wechaty-gateway [options]

Options:
  -p, --puppet <name>    Puppet package name (e.g., @wechatferry/puppet)
  -c, --config <path>    Path to config file (JSON)
  --port <port>          gRPC server port (default: 8788)
  --host <host>          gRPC server host (default: 0.0.0.0)
  -t, --token <token>    Authentication token (auto-generated if not set)
  --no-tls               Disable TLS (for local development)
  --no-auto-install      Disable auto-install of missing puppet
  -h, --help             Display help
```

### Config File

Create a JSON config file:

```json
{
  "puppet": "@wechatferry/puppet",
  "puppetOptions": {
    "// any puppet-specific options": "go here"
  },
  "port": 8788,
  "host": "0.0.0.0",
  "token": "insecure_my-secret-token",
  "tls": false
}
```

### Environment Variables

```bash
WECHATY_GATEWAY_PUPPET=@wechatferry/puppet
WECHATY_GATEWAY_PORT=8788
WECHATY_GATEWAY_HOST=0.0.0.0
WECHATY_GATEWAY_TOKEN=insecure_my-token
WECHATY_GATEWAY_NO_TLS=true
```

Priority: CLI args > Environment variables > Config file > Defaults

## Connecting from Your App

In your Wechaty app (e.g., moltbot-wechaty), configure the puppet service client:

```yaml
# config.yaml
channels:
  wechaty:
    puppet: "@juzi/wechaty-puppet-service"
    puppetOptions:
      endpoint: "gateway-server:8788"
      token: "insecure_my-secret-token"
      tls:
        disable: true
```

Or programmatically:

```typescript
import { WechatyBuilder } from 'wechaty'

const bot = WechatyBuilder.build({
  puppet: '@juzi/wechaty-puppet-service',
  puppetOptions: {
    endpoint: 'gateway-server:8788',
    token: 'insecure_my-secret-token',
    tls: { disable: true },
  },
})

await bot.start()
```

## Examples

### WeChatFerry (PC Hook)

```bash
npx wechaty-puppet-gateway \
  --puppet @wechatferry/puppet \
  --port 8788 \
  --token insecure_wcferry-dev
```

### PadLocal

```bash
npx wechaty-puppet-gateway \
  --config padlocal.config.json
```

```json
{
  "puppet": "wechaty-puppet-padlocal",
  "puppetOptions": {
    "token": "YOUR_PADLOCAL_TOKEN"
  },
  "port": 8788,
  "token": "insecure_padlocal-gw"
}
```

### Mock (for testing)

```bash
npx wechaty-puppet-gateway \
  --puppet @juzi/wechaty-puppet-mock \
  --port 8788
```

## Token Format

Tokens should be prefixed with an SNI identifier for TLS. For local/insecure usage:

```
insecure_<your-identifier>
```

For production with TLS, use a proper UUID:

```
yourservice_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

## Auto-Install

By default, the gateway will automatically install missing puppet packages. This happens when:

1. You run `npx wechaty-puppet-gateway --puppet @wechatferry/puppet`
2. The package `@wechatferry/puppet` is not found
3. Gateway prompts and installs it via npm/yarn/pnpm

Disable with `--no-auto-install`.

## License

Apache-2.0