lauther-client 0.2.0

package/README.md

@@ -0,0 +1,177 @@
+# lauther-client
+
+Push notifications to your phone from any web app or script — and questions
+that **wait for a yes** before something irreversible happens.
+
+Zero dependencies. Node 18+. Two methods.
+
+```bash
+npm install lauther-client
+```
+
+## Why this exists
+
+A browser tab cannot reach someone who has closed it. Building a native app
+per project to fix that is not a plan. Lauther is one app your projects share
+over an HTTP call, so any of them can reach a real phone.
+
+## Send a notification
+
+```js
+import { Lauther } from "lauther-client";
+
+const lauther = new Lauther(process.env.LAUTHER_TOKEN);
+
+await lauther.push({
+  title: "New signup",
+  message: "alex@example.com just created an account",
+});
+```
+
+Get a token in the app: **Apps → ＋ → New token**. It pushes to your phone and
+nobody else's, and you can revoke it any time.
+
+## Ask a question and wait for the answer
+
+This is the part that has no equivalent in a normal push service. The call
+blocks until you press a button on your phone, then returns what you pressed.
+
+```js
+if (await lauther.ask("Deploy v2.4 to production?")) {
+  await deploy();
+}
+```
+
+**Only an explicit Approve returns `true`.** A denial and a timeout both
+return `false` — an unanswered question must never read as a yes.
+
+### Waiting longer than 25 seconds
+
+The API long-polls for at most 25 seconds, which suits a shell one-liner and
+not a script whose human has wandered off. Pass `timeoutSeconds` and the client
+keeps asking about the **same** notification past that, so a ten-minute wait
+still puts one question on the phone rather than one every half minute:
+
+```js
+const out = await lauther.requestApproval("Restore last night's snapshot?", {
+  timeoutSeconds: 600,
+  requireBiometric: true,
+});
+// { id, response: "approve" | "deny" | null, confirmedBy, waitedSeconds }
+```
+
+`response: null` means nobody answered. That is a returned outcome rather than
+a thrown error, deliberately — throwing invites a `catch` that treats silence
+as success.
+
+Useful for anything you would regret doing automatically: a deploy, a refund,
+a database restore, or an AI agent about to act on your behalf.
+
+```js
+// Demand a fingerprint before the approval counts.
+const { response } = await lauther.approve({
+  title: "Refund €240 to order #1183?",
+  message: "Requested by support agent Kim",
+  requireBiometric: true,
+  approveTitle: "Refund",
+  denyTitle: "Keep",
+  wait: 25,
+});
+// response is "approve", "deny", or null when nobody answered in time.
+```
+
+## Handling failure
+
+```js
+import { Lauther, LautherError } from "lauther-client";
+
+try {
+  await lauther.push({ title: "Backup finished" });
+} catch (err) {
+  if (err instanceof LautherError) {
+    console.error(err.status, err.code, err.message);
+  }
+}
+```
+
+Branch on `err.code`, never on `err.message` — messages are written for people
+and may be reworded. A network failure is reported as unreachable rather than
+as a refusal, because those need different handling.
+
+## Knowing whether it arrived
+
+`push()` resolves with what actually happened:
+
+```js
+const { delivered, devices } = await lauther.push({ title: "Hello" });
+```
+
+`delivered: 0` with `devices: 0` means **no phone is registered** on the
+account — usually the app has not been opened since signing in. That is a
+different problem from every device rejecting the message, so the two are
+reported separately rather than collapsed into one flag.
+
+## API
+
+| | |
+| --- | --- |
+| `new Lauther(token, options?)` | `options`: `baseUrl`, `fetch`, `timeoutMs` |
+| `push(options)` | `title`, `message`, `priority`, `url`, `path`, `tag`, `icon`, `color`, `sound`, `image` |
+| `approve(options)` | `title`, `message`, `wait` (0–25s), `approveTitle`, `denyTitle`, `requireBiometric`, `priority` |
+| `requestApproval(question, options?)` | Ask and wait, past the 25s cap, on one notification |
+| `poll(id)` | Ask about an approval already started |
+| `ask(question, options?)` | `requestApproval()` reduced to a boolean |
+
+`priority` runs `-2` to `2`. **`2` is the only level that crosses quiet
+hours** — worth setting on about three things and no more.
+
+Images require a Supporter account. Without one the image is dropped and the
+notification still arrives, because a script should not start failing over an
+entitlement.
+
+TypeScript types are bundled; there is no `@types` package to install.
+
+## You do not need this package
+
+The whole client is `fetch` against two documented endpoints. If you would
+rather not add a dependency, this is the entire integration:
+
+```js
+await fetch("https://api.lauther.id/v1/push", {
+  method: "POST",
+  headers: {
+    Authorization: `Bearer ${process.env.LAUTHER_TOKEN}`,
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({ title: "Backup finished" }),
+});
+```
+
+That is deliberate. A service you can leave in one line has to keep earning
+you.
+
+## Worth knowing before you build on it
+
+- **Hosted only.** The relay holds the APNs connection and the identity
+  layer, which is the part that cannot meaningfully run on your own box.
+- **Not end-to-end encrypted.** Message bodies travel over TLS and are
+  readable by the service. Do not route secrets through it.
+- **Pushover-compatible.** Tools that let you change the Pushover *server
+  URL* work by pointing them at `https://api.lauther.id`, so moving your
+  senders elsewhere later is a URL change rather than a rewrite.
+
+## Using this from a coding agent
+
+[`lauther-mcp`](https://www.npmjs.com/package/lauther-mcp) wraps this as an MCP
+server, so Claude Code, Cursor or Windsurf can ask you for approval on your
+phone before doing something irreversible.
+
+## Links
+
+- Docs — https://lauther.app/docs.html
+- The app — [App Store](https://apps.apple.com/app/id6802635695) · [Google Play](https://play.google.com/store/apps/details?id=id.lauther)
+- Recipes for curl, Python, Home Assistant, Uptime Kuma, GitHub Actions —
+  https://github.com/csanadymiklos/lauther-examples
+- Something wrong? **hello@lauther.id** reaches a human.
+
+MIT

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "lauther-client",
+  "version": "0.2.0",
+  "description": "Send push notifications to your phone from any web app or script — and ask questions that wait for a yes.",
+  "keywords": [
+    "push",
+    "notifications",
+    "push-notifications",
+    "approval",
+    "human-in-the-loop",
+    "agent",
+    "webhook",
+    "ios",
+    "android",
+    "lauther",
+    "lauther-client"
+  ],
+  "homepage": "https://lauther.app",
+  "bugs": {
+    "url": "https://github.com/csanadymiklos/lauther-js/issues"
+  },
+  "license": "MIT",
+  "author": "Dipling Kft.",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/csanadymiklos/lauther-js.git",
+    "directory": "packages/lauther-client"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Priority. 2 is the only level that crosses quiet hours — the setting you
+ * want on about three things and no more.
+ */
+export type Priority = -2 | -1 | 0 | 1 | 2;
+
+export interface PushOptions {
+  /** Shown as the notification's headline. Trimmed to 250 characters. */
+  title?: string;
+  /** The body. Trimmed to 2000 characters. */
+  message?: string;
+  priority?: Priority;
+  /** A link the notification opens. Use `path` instead for a paired site. */
+  url?: string;
+  /** Path on your paired site. Opens signed in; must be same-origin. */
+  path?: string;
+  /** Groups related notifications so a new one replaces the last. */
+  tag?: string;
+  icon?: string;
+  color?: string;
+  sound?: string;
+  /** Image URL. Supporter accounts only; otherwise dropped, never fatal. */
+  image?: string;
+  /** Base64 image. Same entitlement as `image`. */
+  imageBase64?: string;
+}
+
+export interface PushResult {
+  ok: true;
+  id: string;
+  /** Devices that took the message. 0 with `devices: 0` means none registered. */
+  delivered: number;
+  /** Devices Lauther tried. */
+  devices: number;
+  /** `"stored"`, or `"omitted_not_entitled"` when the account cannot attach images. */
+  image?: "stored" | "omitted_not_entitled";
+  /** Present only when every device rejected it. */
+  reason?: "devices_rejected";
+  errors?: Record<string, unknown>;
+}
+
+export interface ApproveOptions {
+  /** The question. Required — it is what you are being asked to approve. */
+  title: string;
+  message?: string;
+  /** Seconds to wait for an answer, 0-25. Defaults to 25. */
+  wait?: number;
+  /** Label on the approve button. Defaults to "Approve". */
+  approveTitle?: string;
+  /** Label on the deny button. Defaults to "Deny". */
+  denyTitle?: string;
+  /**
+   * Demand a fingerprint or face before Approve is accepted. Denying never
+   * requires one — refusing should always be cheap.
+   */
+  requireBiometric?: boolean;
+  priority?: Priority;
+}
+
+export interface ApproveResult {
+  ok: true;
+  id: string;
+  /** `null` means nobody answered in time. Silence is not consent. */
+  response: "approve" | "deny" | null;
+}
+
+export interface PollResult {
+  /** `null` until someone answers. */
+  response: "approve" | "deny" | null;
+  /** How the answer was confirmed, e.g. a biometric check. `null` if not. */
+  confirmedBy: string | null;
+}
+
+export interface WaitOptions extends Omit<ApproveOptions, "title" | "wait"> {
+  /**
+   * How long to wait in total, in seconds. The server long-polls for the
+   * first 25s; beyond that the client polls the same notification, so the
+   * person still sees exactly one question.
+   */
+  timeoutSeconds?: number;
+  /** Gap between polls once past the server's 25s window. Defaults to 3000. */
+  pollIntervalMs?: number;
+}
+
+export interface ApprovalOutcome {
+  id: string;
+  /** `null` means nobody answered in time. Silence is not consent. */
+  response: "approve" | "deny" | null;
+  confirmedBy: string | null;
+  waitedSeconds: number;
+}
+
+export interface LautherOptions {
+  baseUrl?: string;
+  fetch?: typeof globalThis.fetch;
+  /** Client-side abort. Defaults to 40s, comfortably past the 25s server wait. */
+  timeoutMs?: number;
+}
+
+export declare class LautherError extends Error {
+  name: "LautherError";
+  /** HTTP status, absent when the request never reached the server. */
+  status?: number;
+  /** Machine-readable reason. Branch on this, never on `message`. */
+  code?: string;
+  body?: unknown;
+}
+
+export declare class Lauther {
+  constructor(token: string, options?: LautherOptions);
+  token: string;
+  baseUrl: string;
+  timeoutMs: number;
+  push(options: PushOptions): Promise<PushResult>;
+  approve(options: ApproveOptions): Promise<ApproveResult>;
+  /** Ask about an approval already started, by its notification id. */
+  poll(id: string): Promise<PollResult>;
+  /** Ask and wait, past the server's 25s cap, on one notification. */
+  requestApproval(question: string, options?: WaitOptions): Promise<ApprovalOutcome>;
+  /** True only on an explicit Approve; a denial and a timeout are both false. */
+  ask(question: string, options?: WaitOptions): Promise<boolean>;
+}
+
+export declare function push(options: PushOptions): Promise<PushResult>;
+export declare function ask(question: string, options?: WaitOptions): Promise<boolean>;
+
+export default Lauther;

package/src/index.js

@@ -0,0 +1,259 @@
+/**
+ * Lauther — push notifications and human approvals for anything that can make
+ * an HTTP request.
+ *
+ * Zero dependencies on purpose. The whole client is `fetch` against two
+ * documented endpoints, so there is no SDK to go stale against the API and
+ * nothing to audit before you install it. If this package ever disappears,
+ * the four lines it replaces are in the README.
+ *
+ * @see https://lauther.app/docs.html
+ */
+
+const DEFAULT_BASE_URL = "https://api.lauther.id";
+
+/** The server caps its own wait at 25s; going higher just idles the socket. */
+const MAX_WAIT_SECONDS = 25;
+
+/**
+ * An error carrying what the API actually said.
+ *
+ * `code` is the machine-readable reason where the API supplies one (for
+ * example `alias_limit_reached`, `cross_origin_path`). Branch on `code`,
+ * never on `message` — messages are written for people and may be reworded.
+ */
+export class LautherError extends Error {
+  /**
+   * @param {string} message
+   * @param {{status?: number, code?: string, body?: unknown}} [detail]
+   */
+  constructor(message, detail = {}) {
+    super(message);
+    this.name = "LautherError";
+    this.status = detail.status;
+    this.code = detail.code;
+    this.body = detail.body;
+  }
+}
+
+/**
+ * @param {unknown} v
+ * @returns {v is Record<string, unknown>}
+ */
+const isObject = (v) => typeof v === "object" && v !== null;
+
+/** Drop undefined so we never send `"title": undefined` and confuse a proxy. */
+const compact = (obj) => {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) if (v !== undefined) out[k] = v;
+  return out;
+};
+
+export class Lauther {
+  /**
+   * @param {string} token Your `lpt_…` token. In the app: Apps → ＋ → New token.
+   * @param {{baseUrl?: string, fetch?: typeof globalThis.fetch, timeoutMs?: number}} [options]
+   */
+  constructor(token, options = {}) {
+    if (!token || typeof token !== "string") {
+      throw new LautherError(
+        "A Lauther token is required. Mint one in the app under " +
+        "Apps → ＋ → New token, then pass it as new Lauther(token).");
+    }
+    this.token = token;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeoutMs = options.timeoutMs ?? 40_000;
+    // Captured rather than looked up per call so tests can inject one, and so
+    // a caller who polyfills after construction gets predictable behaviour.
+    this._fetch = options.fetch ?? globalThis.fetch;
+    if (typeof this._fetch !== "function") {
+      throw new LautherError(
+        "No fetch available. Node 18+ has it built in; on older runtimes " +
+        "pass one: new Lauther(token, { fetch }).");
+    }
+  }
+
+  /**
+   * Send a notification. Resolves once Lauther has accepted it.
+   *
+   * Note `delivered` in the result: it counts devices that actually took the
+   * message. `delivered: 0` with `devices: 0` means no phone is registered on
+   * the account — usually the app has not been opened since signing in — and
+   * is not the same failure as every device rejecting it.
+   *
+   * @param {import("./index.d.ts").PushOptions} options
+   */
+  async push(options) {
+    const {title, message, ...rest} = options ?? {};
+    if (!title && !message) {
+      throw new LautherError("push() needs a title or a message.");
+    }
+    return this.#request("/v1/push", {title, message, ...rest});
+  }
+
+  /**
+   * Put Approve / Deny on your phone and wait for the answer.
+   *
+   * The request blocks server-side for up to 25 seconds. `response` is
+   * `"approve"`, `"deny"`, or `null` when nobody answered in time — three
+   * outcomes, and silence is not consent.
+   *
+   * @param {import("./index.d.ts").ApproveOptions} options
+   */
+  async approve(options) {
+    const {title, wait = MAX_WAIT_SECONDS, ...rest} = options ?? {};
+    if (!title) throw new LautherError("approve() needs a title — it is the question.");
+    return this.#request("/v1/approve", {
+      title,
+      wait: Math.min(Math.max(Number(wait) || 0, 0), MAX_WAIT_SECONDS),
+      ...rest,
+    });
+  }
+
+  /**
+   * Ask about an approval you already started, by its notification id.
+   *
+   * Note this endpoint takes the token in the body rather than as a bearer
+   * header — that is the API's shape, not a mistake here.
+   *
+   * @param {string} id The `id` returned by `approve()`.
+   * @returns {Promise<import("./index.d.ts").PollResult>}
+   */
+  async poll(id) {
+    if (!id) throw new LautherError("poll() needs the id returned by approve().");
+    return this.#request("/v1/action/poll", {token: this.token, id});
+  }
+
+  /**
+   * Ask a question and wait for the answer, for as long as you are willing.
+   *
+   * The server caps its own long-poll at 25 seconds, which suits a shell
+   * one-liner and not an agent whose owner has wandered off. Past that, this
+   * keeps asking about the SAME notification rather than sending another one,
+   * so the person sees one question on their phone and not a pile of them.
+   *
+   * @param {string} question
+   * @param {import("./index.d.ts").WaitOptions} [options]
+   * @returns {Promise<import("./index.d.ts").ApprovalOutcome>}
+   */
+  async requestApproval(question, options = {}) {
+    const {
+      timeoutSeconds = MAX_WAIT_SECONDS,
+      pollIntervalMs = 3000,
+      ...rest
+    } = options;
+    const startedAt = Date.now();
+    const elapsed = () => (Date.now() - startedAt) / 1000;
+
+    const started = await this.approve({
+      title: question,
+      wait: Math.min(timeoutSeconds, MAX_WAIT_SECONDS),
+      ...rest,
+    });
+    if (started.response) {
+      return {
+        id: started.id, response: started.response,
+        confirmedBy: started.confirmedBy ?? null, waitedSeconds: Math.round(elapsed()),
+      };
+    }
+
+    while (elapsed() < timeoutSeconds) {
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+      const {response, confirmedBy} = await this.poll(started.id);
+      if (response) {
+        return {
+          id: started.id, response,
+          confirmedBy: confirmedBy ?? null, waitedSeconds: Math.round(elapsed()),
+        };
+      }
+    }
+    // Nobody answered. Deliberately NOT an error: "no answer" is a real
+    // outcome a caller must handle, and throwing would tempt a catch that
+    // treats it as a yes.
+    return {
+      id: started.id, response: null, confirmedBy: null,
+      waitedSeconds: Math.round(elapsed()),
+    };
+  }
+
+  /**
+   * `requestApproval()` reduced to a boolean, for the common `if` around
+   * something irreversible.
+   *
+   * **Only an explicit Approve returns true.** A denial and a timeout both
+   * return false, which is the safe way round: an unanswered question must
+   * never read as a yes.
+   *
+   * @param {string} question
+   * @param {import("./index.d.ts").WaitOptions} [options]
+   * @returns {Promise<boolean>}
+   */
+  async ask(question, options = {}) {
+    const out = await this.requestApproval(question, options);
+    return out.response === "approve";
+  }
+
+  /**
+   * @param {string} path
+   * @param {Record<string, unknown>} body
+   */
+  async #request(path, body) {
+    let res;
+    try {
+      res = await this._fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${this.token}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(compact(body)),
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (cause) {
+      // A timeout here is the network, not a denial. Say so, because the
+      // caller's next decision depends on telling those apart.
+      throw new LautherError(
+        `Could not reach Lauther at ${this.baseUrl}${path}: ${cause?.message ?? cause}`,
+        {body: undefined});
+    }
+
+    const text = await res.text();
+    let parsed;
+    try {
+      parsed = text ? JSON.parse(text) : {};
+    } catch {
+      parsed = {raw: text};
+    }
+
+    if (!res.ok) {
+      const code = isObject(parsed) && typeof parsed.code === "string" ?
+        parsed.code : undefined;
+      const message = isObject(parsed) && typeof parsed.error === "string" ?
+        parsed.error : `HTTP ${res.status}`;
+      throw new LautherError(message, {status: res.status, code, body: parsed});
+    }
+    return parsed;
+  }
+}
+
+/**
+ * Convenience for the one-liner case, reading the token from
+ * `process.env.LAUTHER_TOKEN`.
+ *
+ * @param {import("./index.d.ts").PushOptions} options
+ */
+export function push(options) {
+  return new Lauther(process.env?.LAUTHER_TOKEN).push(options);
+}
+
+/**
+ * As `push`, for a question. Returns true only on an explicit Approve.
+ *
+ * @param {string} question
+ * @param {Omit<import("./index.d.ts").ApproveOptions, "title">} [options]
+ */
+export function ask(question, options) {
+  return new Lauther(process.env?.LAUTHER_TOKEN).ask(question, options);
+}
+
+export default Lauther;