@zeph-to/hook-sdk

Push notification SDK + CLI for Zeph. Zero dependencies — uses native fetch.

Installation

npm install @zeph-to/hook-sdk
# or
npx @zeph-to/hook-sdk notify --title "Hello"

Quick Start

# Interactive — detects agents, saves config, installs plugins
npx @zeph-to/hook-sdk install

# Non-interactive (one line from Zeph app)
npx @zeph-to/hook-sdk install --key ak_... --hook hook_...

Saves to ~/.zeph/config.json. All Zeph tools (CLI, MCP server, plugin hooks) read this file.

CLI Usage

# Send a notification
zeph notify --title "Deploy done" --body "v2.1.0 shipped"

# Send with priority
zeph notify --title "Build failed" --priority high --url https://ci.example.com/123

# List recent pushes
zeph list
zeph list --limit 10 --type note

# Dismiss a push
zeph dismiss push_01JXY...
zeph dismiss --all

# Test connection
zeph test

# JSON output
zeph notify --title "Hello" --json

Commands

| Command | Description | |---------|-------------| | install | One-command setup: detect agents, save config, install plugins | | notify | Send a push notification | | list | List recent push notifications | | dismiss <id> | Dismiss a push (or --all) | | test | Verify connection and API key |

Notify Options

| Flag | Description | |------|-------------| | --title <text> | Push title | | --body <text> | Push body | | --url <url> | URL to include | | --type <type> | Push type: note, link, file, hook | | --priority <p> | Priority: low, normal, high, urgent | | --device <id> | Target device ID |

List Options

| Flag | Description | |------|-------------| | --limit <n> | Number of pushes (1-20, default 5) | | --type <type> | Filter by push type |

Global Options

| Flag | Description | |------|-------------| | --key <api-key> | API key (or set ZEPH_API_KEY env) | | --base-url <url> | API base URL (or set ZEPH_BASE_URL env) | | --json | Output JSON format | | --version | Print version |

Mute

Mute is project-scoped (uses project directory hash). Created by Claude Code /zeph-mute command.

Notifications are silently skipped when a mute file exists for the current project:

# Mute (created by /zeph-mute in Claude Code plugin)
HASH=$(echo -n "$PROJECT_DIR" | cksum | cut -d' ' -f1)
touch /tmp/zeph-muted-$HASH

# Unmute
rm /tmp/zeph-muted-$HASH

The CLI checks CLAUDE_PROJECT_DIR, CURSOR_PROJECT_DIR, WINDSURF_PROJECT_DIR, and falls back to cwd.

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Quota exceeded | | 3 | Authentication failed |

Environment Variables

| Variable | Description | |----------|-------------| | ZEPH_API_KEY | API key (fallback when --key not provided) | | ZEPH_BASE_URL | API base URL (default: https://api.zeph.to/v1) |

SDK Usage

import { ZephHook } from '@zeph-to/hook-sdk';

const hook = new ZephHook({ apiKey: 'ak_...' });

// Notify
const result = await hook.notify({
  title: 'Build Complete',
  body: 'Deploy succeeded',
  url: 'https://example.com/deploy/123',
  priority: 'high',
});
console.log(result.pushId); // 'push_01JXY...'

// List
const list = await hook.list({ limit: 5 });
console.log(list.pushes);

// Dismiss
await hook.dismiss('push_01JXY...');
await hook.dismissAll();

Constructor Options

| Field | Type | Description | |-------|------|-------------| | apiKey | string | Required — API key from Zeph settings | | baseUrl | string? | API base URL (default: https://api.zeph.to/v1) | | timeout | number? | Request timeout in ms (default: 30000) |

Notify Payload

| Field | Type | Description | |-------|------|-------------| | title | string? | Push title | | body | string? | Push body | | url | string? | URL to include | | type | 'note' \| 'link' \| 'file' \| 'hook'? | Push type (default: hook) | | priority | 'low' \| 'normal' \| 'high' \| 'urgent'? | Priority (default: normal) | | targetDeviceId | string? | Send to specific device |

Error Handling

import { ZephHook, AuthenticationError, QuotaExceededError, ZephError } from '@zeph-to/hook-sdk';

try {
  await hook.notify({ title: 'Hello' });
} catch (err) {
  if (err instanceof AuthenticationError) { /* Invalid API key */ }
  if (err instanceof QuotaExceededError) { /* Monthly limit reached */ }
  if (err instanceof ZephError) { /* Other API error */ }
}

Supported Agents

zeph install detects and configures these agents automatically:

| Agent | What gets installed | |-------|-------------------| | Claude Code | Plugin (hooks + MCP server) | | Cursor | MCP server + stop hook + rules | | Windsurf | MCP server + response hook | | Gemini CLI | MCP server + AfterAgent hook | | Codex CLI | Stop hook | | Copilot CLI | Session end hook | | Cline | Rules file |

Requirements

• Node.js >= 18 (uses native fetch)
• Zero runtime dependencies

License

Apache-2.0