@piplfy/widget 0.0.1

package/README.md

@@ -0,0 +1,190 @@
+# Piplfy Widget
+
+Native WebSocket bridge that runs as a sidecar process alongside your Node.js application. Handles real-time communication with the Piplfy platform through an embedded Rust binary — no native compilation required on install.
+
+## Install
+
+```bash
+npm install piplfy-widget
+```
+
+The correct binary for your OS and architecture is installed automatically. No extra steps needed.
+
+### Supported platforms
+
+| Platform | Architecture | Package |
+| -------- | ------------ | ------- |
+| Linux | x64 | `piplfy-widget-linux-x64` |
+| Windows | x64 | `piplfy-widget-win32-x64` |
+
+> macOS and ARM support coming soon.
+
+## Quick start
+
+```javascript
+import { startPwidget } from "piplfy-widget";
+
+const widget = await startPwidget({
+  onLog: (line) => console.log("[pwidget]", line),
+});
+
+// The binary is now running and listening for WebSocket connections.
+// When you're done:
+widget.kill();
+```
+
+## API
+
+### `startPwidget(options?)`
+
+Starts the native binary as a child process. Returns a Promise that resolves once the process is ready (emits `"listening on"` to stdout).
+
+**Options:**
+
+| Parameter | Type | Default | Description |
+| --------- | ---- | ------- | ----------- |
+| `timeout` | `number` | `5000` | Max milliseconds to wait for startup before rejecting |
+| `env` | `Record<string, string>` | `{}` | Extra environment variables passed to the binary |
+| `onLog` | `(data: string) => void` | — | Called on every stdout/stderr chunk |
+| `onExit` | `(code: number \| null) => void` | — | Called when the process exits |
+
+**Returns:** `Promise<{ kill: () => void, process: ChildProcess }>`
+
+```javascript
+const widget = await startPwidget({
+  timeout: 8000,
+  env: {
+    PORT: "9090",
+    PWIDGET_SECRET: process.env.PWIDGET_SECRET,
+  },
+  onLog: (line) => console.log("[pwidget]", line),
+  onExit: (code) => {
+    if (code !== 0) console.error("pwidget crashed with code", code);
+  },
+});
+```
+
+### `resolveBinaryPath()`
+
+Returns the absolute path to the native binary for the current platform. Useful if you want to manage the process yourself.
+
+```javascript
+import { resolveBinaryPath } from "piplfy-widget";
+
+const binaryPath = resolveBinaryPath();
+// => "/path/to/node_modules/piplfy-widget-linux-x64/bin/pwidget"
+```
+
+## CLI
+
+You can also run the binary directly from the command line:
+
+```bash
+npx piplfy-widget
+```
+
+## Zod schemas
+
+The package exports Zod validation schemas that match the data structures expected by the binary. Zod is an optional peer dependency — if you don't use the schemas, you don't need to install it.
+
+```bash
+npm install zod
+```
+
+```javascript
+import { userContextSchema } from "piplfy-widget/schemas";
+
+const result = userContextSchema.safeParse(payload);
+
+if (!result.success) {
+  console.error(result.error.issues);
+  return;
+}
+
+// result.data is fully typed
+console.log(result.data.email);
+console.log(result.data.organization.domain);
+```
+
+The `userContextSchema` validates the following shape:
+
+```typescript
+{
+  id: string
+  username: string | null
+  email: string              // validated as email
+  profile: {
+    firstname: string
+    lastname: string | null
+    phone: string | null
+  }
+  organization: {
+    name: string
+    domain: string
+    public_domain: string | null
+    description: string | null
+    country_id: string | null  // validated as UUID
+    sector_id: string | null   // validated as UUID
+    size_id: string | null     // validated as UUID
+    target_countries: string[] | null
+    target_sectors: string[] | null
+    target_sizes: string[] | null
+    target_tags: string[] | null
+    logo_url: string | null    // validated as URL
+  }
+}
+```
+
+## Usage with Express
+
+A common pattern is to proxy WebSocket connections from your Express server to the native binary:
+
+```javascript
+import express from "express";
+import http from "http";
+import httpProxy from "http-proxy";
+import { startPwidget } from "piplfy-widget";
+
+const app = express();
+const server = http.createServer(app);
+
+const proxy = httpProxy.createProxyServer({
+  target: "http://localhost:8080",
+  ws: true,
+});
+
+await startPwidget({
+  env: { PORT: "8080" },
+  onLog: (line) => console.log("[pwidget]", line),
+  onExit: (code) => {
+    console.error("pwidget exited unexpectedly:", code);
+    process.exit(1);
+  },
+});
+
+app.get("/health", (req, res) => res.json({ status: "ok" }));
+
+server.on("upgrade", (req, socket, head) => {
+  if (req.url === "/ws") {
+    proxy.ws(req, socket, head);
+  } else {
+    socket.destroy();
+  }
+});
+
+server.listen(3000, () => {
+  console.log("Server listening on :3000");
+});
+```
+
+## Troubleshooting
+
+**`piplfy-widget: plataforma "X" no soportada`** — Your OS/arch combination doesn't have a prebuilt binary yet. See the supported platforms table above.
+
+**`pwidget failed to start within 5000ms`** — The binary didn't emit `"listening on"` in time. Try increasing the `timeout` option or check the logs with `onLog`.
+
+**`no se encontró el paquete "piplfy-widget-..."`** — The platform-specific package didn't install. Run `npm install` again, or install it explicitly: `npm install piplfy-widget-linux-x64`.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import { resolveBinaryPath } from "../lib/resolve.js";
+
+const binary = resolveBinaryPath();
+
+try {
+	execFileSync(binary, process.argv.slice(2), {
+		stdio: "inherit",
+	});
+} catch (err) {
+	if (err.status !== null) {
+		process.exit(err.status);
+	}
+	console.error(`Failed to run piplfy-widget: ${err.message}`);
+	process.exit(1);
+}

package/lib/index.js

@@ -0,0 +1,84 @@
+import { spawn } from "node:child_process";
+import { resolveBinaryPath } from "./resolve.js";
+
+export { resolveBinaryPath } from "./resolve.js";
+
+/**
+ * Inicia el binario pwidget como proceso hijo.
+ *
+ * @param {object} [options]
+ * @param {number} [options.timeout=5000]   - Tiempo máximo de espera para el arranque (ms)
+ * @param {Record<string, string>} [options.env] - Variables de entorno extra para el proceso
+ * @param {(data: string) => void} [options.onLog]  - Callback para cada línea de log
+ * @param {(code: number | null) => void} [options.onExit] - Callback al terminar el proceso
+ * @returns {Promise<{ kill: () => void, process: import("child_process").ChildProcess }>}
+ *
+ * @example
+ * ```js
+ * import { startPwidget } from "piplfy-widget";
+ *
+ * const widget = await startPwidget({
+ *   timeout: 8000,
+ *   env: { PORT: "9090" },
+ *   onLog: (line) => console.log("[pwidget]", line),
+ *   onExit: (code) => console.log("Exited with", code),
+ * });
+ *
+ * // Cuando quieras pararlo:
+ * widget.kill();
+ * ```
+ */
+export function startPwidget(options = {}) {
+	const { timeout = 5000, env, onLog, onExit } = options;
+
+	return new Promise((resolve, reject) => {
+		const binaryPath = resolveBinaryPath();
+
+		const child = spawn(binaryPath, [], {
+			stdio: ["ignore", "pipe", "pipe"],
+			windowsHide: true,
+			env: { ...process.env, ...env },
+		});
+
+		let started = false;
+
+		const timer = setTimeout(() => {
+			if (!started) {
+				child.kill();
+				reject(new Error(`pwidget failed to start within ${timeout}ms`));
+			}
+		}, timeout);
+
+		child.stdout?.on("data", (data) => {
+			const text = data.toString();
+			onLog?.(text);
+
+			if (!started && text.includes("listening on")) {
+				started = true;
+				clearTimeout(timer);
+				resolve({ kill: () => child.kill(), process: child });
+			}
+		});
+
+		child.stderr?.on("data", (data) => {
+			onLog?.(data.toString());
+		});
+
+		child.on("error", (err) => {
+			clearTimeout(timer);
+			if (!started) {
+				reject(new Error(`Failed to start pwidget: ${err.message}`));
+			}
+		});
+
+		child.on("exit", (code) => {
+			clearTimeout(timer);
+			onExit?.(code);
+			if (!started) {
+				reject(
+					new Error(`pwidget exited with code ${code} before starting`),
+				);
+			}
+		});
+	});
+}

package/lib/resolve.js

@@ -0,0 +1,51 @@
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+
+const BINARY_NAME = "pwidget";
+
+const PLATFORM_PACKAGES = {
+	"linux-x64": "@piplfy/widget-linux-x64",
+	"win32-x64": "@piplfy/widget-win32-x64",
+	// "darwin-x64":  "@piplfy/widget-darwin-x64",
+	// "darwin-arm64": "@piplfy/widget-darwin-arm64",
+	// "linux-arm64": "@piplfy/widget-linux-arm64",
+};
+
+/**
+ * Resuelve la ruta al binario nativo para la plataforma actual.
+ * Busca el paquete instalado vía optionalDependencies.
+ * @returns {string} Ruta absoluta al binario
+ */
+export function resolveBinaryPath() {
+	const platform = os.platform();
+	const arch = os.arch();
+	const key = `${platform}-${arch}`;
+
+	const packageName = PLATFORM_PACKAGES[key];
+
+	if (!packageName) {
+		const supported = Object.keys(PLATFORM_PACKAGES).join(", ");
+		throw new Error(
+			`@piplfy/widget: plataforma "${key}" no soportada.\n` +
+				`Plataformas soportadas: ${supported}`,
+		);
+	}
+
+	const ext = platform === "win32" ? ".exe" : "";
+	const binaryFile = `${BINARY_NAME}${ext}`;
+
+	const require = createRequire(import.meta.url);
+
+	try {
+		const packageDir = path.dirname(
+			require.resolve(`${packageName}/package.json`),
+		);
+		return path.join(packageDir, "bin", binaryFile);
+	} catch {
+		throw new Error(
+			`@piplfy/widget: no se encontró el paquete "${packageName}".\n` +
+				`Ejecutá: npm install ${packageName}`,
+		);
+	}
+}

package/lib/schemas.js

@@ -0,0 +1,28 @@
+import * as z from "zod";
+
+export const userContextSchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  username: z.string().nullish(),
+  profile: z.object({
+  firstname: z.string(),
+  lastname: z.string().nullish(),
+  phone: z.string().nullish()
+}),
+  organization: z.object({
+  name: z.string(),
+  domain: z.string(),
+  public_domain: z.string().nullish(),
+  description: z.string().nullish(),
+  country_id: z.string().nullish(),
+  sector_id: z.string().nullish(),
+  size_id: z.string().nullish(),
+  target_countries: z.array(z.string()).nullish(),
+  target_sectors: z.array(z.string()).nullish(),
+  target_sizes: z.array(z.string()).nullish(),
+  target_tags: z.array(z.string()).nullish(),
+  logo_url: z.string().nullish()
+})
+});
+
+/** @typedef {z.infer<typeof userContextSchema>} UserContext */

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@piplfy/widget",
+  "version": "0.0.1",
+  "description": "Piplfy Widget — native WebSocket bridge for Node.js applications",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./schemas": "./lib/schemas.js"
+  },
+  "bin": {
+    "piplfy-widget": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "optionalDependencies": {
+    "@piplfy/widget-linux-x64": "0.0.1",
+    "@piplfy/widget-win32-x64": "0.0.1"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "piplfy",
+    "widget",
+    "websocket",
+    "native",
+    "binary"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}