@zeph-to/hook-sdk 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# @zeph/hook-sdk
+
+Push notification SDK + CLI for [Zeph](https://zeph.to). Zero dependencies — uses native `fetch`.
+
+## Installation
+
+```bash
+npm install @zeph/hook-sdk
+```
+
+## SDK Usage
+
+```typescript
+import { ZephHook } from '@zeph/hook-sdk';
+
+const hook = new ZephHook({ apiKey: 'ak_...' });
+
+const result = await hook.notify({
+  title: 'Build Complete',
+  body: 'Deploy succeeded',
+  url: 'https://example.com/deploy/123',
+});
+
+console.log(result.pushId); // 'push_01JXY...'
+```
+
+### Options
+
+```typescript
+const hook = new ZephHook({
+  apiKey: 'ak_...',          // Required — API key from Zeph settings
+  baseUrl: 'https://...',    // Optional — API base URL (default: https://api.zeph.to)
+  timeout: 30000,            // Optional — 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'?` | Push type (default: `note`) |
+| `targetDeviceId` | `string?` | Send to specific device |
+
+### Error Handling
+
+```typescript
+import { ZephHook, AuthenticationError, QuotaExceededError, ZephError } from '@zeph/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 */ }
+}
+```
+
+## CLI Usage
+
+```bash
+# With API key flag
+zeph notify --key ak_... --title "Deploy done" --body "v2.1.0 shipped"
+
+# With environment variable
+export ZEPH_API_KEY=ak_...
+zeph notify --title "Build failed" --url https://ci.example.com/123
+
+# JSON output
+zeph notify --title "Hello" --json
+```
+
+### CLI Options
+
+| Flag | Description |
+|------|-------------|
+| `--key <api-key>` | API key (or set `ZEPH_API_KEY` env) |
+| `--title <text>` | Push title |
+| `--body <text>` | Push body |
+| `--url <url>` | URL to include |
+| `--type <type>` | Push type: `note`, `link`, `file` |
+| `--device <id>` | Target device ID |
+| `--base-url <url>` | API base URL |
+| `--json` | Output JSON format |
+| `--version` | Print version |
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Quota exceeded |
+| 3 | Authentication failed |
+
+## Requirements
+
+- Node.js >= 18 (uses native `fetch`)
+- Zero runtime dependencies
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
+const path_1 = require("path");
+const zeph_hook_js_1 = require("./zeph-hook.js");
+const errors_js_1 = require("./errors.js");
+const getVersion = () => {
+    try {
+        const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, '..', 'package.json'), 'utf-8'));
+        return pkg.version;
+    }
+    catch {
+        return '0.0.0';
+    }
+};
+// ── Arg Parser ──────────────────────────────────────────────────
+const parseArgs = (argv) => {
+    const result = {};
+    const args = argv.slice(2);
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith('--')) {
+            if (!result._command)
+                result._command = arg;
+            continue;
+        }
+        const key = arg.slice(2);
+        const next = args[i + 1];
+        if (!next || next.startsWith('--')) {
+            result[key] = true;
+        }
+        else {
+            result[key] = next;
+            i++;
+        }
+    }
+    return result;
+};
+// ── Output ──────────────────────────────────────────────────────
+const printUsage = () => {
+    console.log(`Usage: zeph notify [options]
+
+Options:
+  --key <api-key>    API key (or set ZEPH_API_KEY env)
+  --title <text>     Push title
+  --body <text>      Push body
+  --url <url>        URL to include
+  --type <type>      Push type (note|link|file) [default: note]
+  --device <id>      Target device ID
+  --base-url <url>   API base URL
+  --json             Output JSON format
+
+Environment:
+  ZEPH_API_KEY       API key (fallback when --key not provided)`);
+};
+const printError = (message, isJson) => {
+    if (isJson) {
+        console.error(JSON.stringify({ error: message, status: 'error' }));
+    }
+    else {
+        console.error(`Error: ${message}`);
+    }
+};
+const printSuccess = (pushId, isJson) => {
+    if (isJson) {
+        console.log(JSON.stringify({ pushId, status: 'ok' }));
+    }
+    else {
+        console.log(`Push sent: ${pushId}`);
+    }
+};
+// ── Main ────────────────────────────────────────────────────────
+const main = async () => {
+    const args = parseArgs(process.argv);
+    const command = args._command;
+    const isJson = args.json === true;
+    if (args.version === true) {
+        console.log(getVersion());
+        return 0;
+    }
+    if (!command || command === 'help') {
+        printUsage();
+        return 0;
+    }
+    if (command !== 'notify') {
+        printError(`Unknown command: ${command}`, isJson);
+        printUsage();
+        return 1;
+    }
+    const apiKey = args.key || process.env.ZEPH_API_KEY;
+    if (!apiKey) {
+        printError('API key required. Use --key or set ZEPH_API_KEY', isJson);
+        return 3;
+    }
+    const hook = new zeph_hook_js_1.ZephHook({
+        apiKey,
+        baseUrl: args['base-url'],
+    });
+    try {
+        const result = await hook.notify({
+            title: args.title,
+            body: args.body,
+            url: args.url,
+            type: args.type || undefined,
+            targetDeviceId: args.device,
+        });
+        printSuccess(result.pushId, isJson);
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof errors_js_1.QuotaExceededError) {
+            printError(err.message, isJson);
+            return 2;
+        }
+        if (err instanceof errors_js_1.AuthenticationError) {
+            printError(err.message, isJson);
+            return 3;
+        }
+        if (err instanceof errors_js_1.ZephError) {
+            printError(err.message, isJson);
+            return 1;
+        }
+        printError(err instanceof Error ? err.message : 'Unknown error', isJson);
+        return 1;
+    }
+};
+main().then((code) => process.exit(code));

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class ZephError extends Error {
+    code: string;
+    status: number;
+    constructor(message: string, code: string, status: number);
+}
+export declare class AuthenticationError extends ZephError {
+    constructor(message?: string);
+}
+export declare class QuotaExceededError extends ZephError {
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,SAAU,SAAQ,KAAK;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;gBAEH,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM1D;AAED,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,OAAO,SAA0B;CAI9C;AAED,qBAAa,kBAAmB,SAAQ,SAAS;gBACnC,OAAO,SAAmB;CAIvC"}

package/dist/errors.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuotaExceededError = exports.AuthenticationError = exports.ZephError = void 0;
+class ZephError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.name = 'ZephError';
+        this.code = code;
+        this.status = status;
+    }
+}
+exports.ZephError = ZephError;
+class AuthenticationError extends ZephError {
+    constructor(message = 'Authentication failed') {
+        super(message, 'AUTHENTICATION_ERROR', 401);
+        this.name = 'AuthenticationError';
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class QuotaExceededError extends ZephError {
+    constructor(message = 'Quota exceeded') {
+        super(message, 'QUOTA_EXCEEDED', 403);
+        this.name = 'QuotaExceededError';
+    }
+}
+exports.QuotaExceededError = QuotaExceededError;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ZephHook } from './zeph-hook.js';
+export { ZephError, AuthenticationError, QuotaExceededError } from './errors.js';
+export type { ZephOptions, NotifyPayload, NotifyResult } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjF,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuotaExceededError = exports.AuthenticationError = exports.ZephError = exports.ZephHook = void 0;
+var zeph_hook_js_1 = require("./zeph-hook.js");
+Object.defineProperty(exports, "ZephHook", { enumerable: true, get: function () { return zeph_hook_js_1.ZephHook; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "ZephError", { enumerable: true, get: function () { return errors_js_1.ZephError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_js_1.AuthenticationError; } });
+Object.defineProperty(exports, "QuotaExceededError", { enumerable: true, get: function () { return errors_js_1.QuotaExceededError; } });

package/dist/types.d.ts

@@ -0,0 +1,23 @@
+export interface ZephOptions {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+export interface NotifyPayload {
+    title?: string;
+    body?: string;
+    url?: string;
+    type?: 'note' | 'link' | 'file';
+    targetDeviceId?: string;
+}
+export interface NotifyResult {
+    pushId: string;
+}
+export interface ApiErrorResponse {
+    error: {
+        code: string;
+        message: string;
+        status: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH"}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/zeph-hook.d.ts

@@ -0,0 +1,10 @@
+import type { ZephOptions, NotifyPayload, NotifyResult } from './types.js';
+export declare class ZephHook {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(options: ZephOptions);
+    notify(payload: NotifyPayload): Promise<NotifyResult>;
+    private parseError;
+}
+//# sourceMappingURL=zeph-hook.d.ts.map

package/dist/zeph-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zeph-hook.d.ts","sourceRoot":"","sources":["../src/zeph-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAoB,MAAM,YAAY,CAAC;AAM7F,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,EAAE,WAAW;IAS1B,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAqC3D,OAAO,CAAC,UAAU;CASnB"}

package/dist/zeph-hook.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZephHook = void 0;
+const errors_js_1 = require("./errors.js");
+const DEFAULT_BASE_URL = 'https://api.zeph.to';
+const DEFAULT_TIMEOUT_MS = 30_000;
+class ZephHook {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new errors_js_1.ZephError('apiKey is required', 'INVALID_OPTIONS', 400);
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+        this.timeoutMs = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    }
+    async notify(payload) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await fetch(`${this.baseUrl}/v1/pushes/send`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-API-Key': this.apiKey,
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === 'AbortError') {
+                throw new errors_js_1.ZephError(`Request timed out after ${this.timeoutMs}ms`, 'TIMEOUT', 408);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const json = await response.json();
+        if (!response.ok) {
+            throw this.parseError(response.status, json);
+        }
+        const pushId = json.data?.pushId;
+        if (!pushId) {
+            throw new errors_js_1.ZephError('Server returned no pushId', 'INVALID_RESPONSE', response.status);
+        }
+        return { pushId };
+    }
+    parseError(status, body) {
+        const message = body.error?.message ?? `Request failed with status ${status}`;
+        const code = body.error?.code ?? 'UNKNOWN_ERROR';
+        if (status === 401)
+            return new errors_js_1.AuthenticationError(message);
+        if (status === 403 && code === 'QUOTA_EXCEEDED')
+            return new errors_js_1.QuotaExceededError(message);
+        return new errors_js_1.ZephError(message, code, status);
+    }
+}
+exports.ZephHook = ZephHook;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@zeph-to/hook-sdk",
+  "version": "0.1.0",
+  "description": "Zeph push notification SDK + CLI — zero dependencies",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "zeph": "./dist/cli.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tak-bro/encl",
+    "directory": "libs/hook-sdk"
+  },
+  "homepage": "https://github.com/tak-bro/encl/tree/main/libs/hook-sdk",
+  "keywords": ["zeph", "push", "notification", "cli", "webhook"],
+  "license": "MIT"
+}