lauther-client 0.2.0 → 0.3.0

package/README.md

@@ -3,7 +3,7 @@
 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.
+Zero dependencies. Node 18+.
 
 ```bash
 npm install lauther-client
@@ -80,6 +80,50 @@ const { response } = await lauther.approve({
 // response is "approve", "deny", or null when nobody answered in time.
 ```
 
+## Requests
+
+A request is an approval whose "yes" carries something back: the person taps
+**Share**, the phone does one thing while they watch, and the result rides
+home on the answer. Two kinds: where they are, and one picture.
+
+```js
+const where = await lauther.requestLocation({
+  title: "Share your location so I can find the nearest pharmacy?",
+  timeoutSeconds: 300,
+});
+
+if (where.response === "approve") {
+  const { lat, lng, accuracy, at } = where.result;
+}
+```
+
+```js
+const shot = await lauther.requestPhoto({ title: "Photo of the printer display?" });
+
+if (shot.response === "approve") {
+  const { url, bytes, width, height } = shot.result; // a JPEG download link
+}
+```
+
+Both return `{ id, response, confirmedBy, result, waitedSeconds, expired }`.
+`response` is `"approve"`, `"deny"` or `null`, and `result` is `null` unless
+the person approved. They wait the way `requestApproval()` does: past the
+server's 25 seconds on the **same** request, so the phone still shows one.
+Silence is a returned outcome rather than a thrown error. `expired: true`
+means the request lapsed on the phone (10 minutes by default; set
+`expiresIn`, 60 to 3600 seconds) and the wait ends early.
+
+- **Location** is one reading, taken when they tap Share and sent once:
+  `{ lat, lng, accuracy, at }`, with `accuracy` in metres.
+- **Photo** is a JPEG they take or pick, at most 2 MB. You receive a link,
+  and **the link works for 7 days**; download it if you want to keep it.
+
+Options for both: `title`, `message`, `requireBiometric`, `priority`,
+`expiresIn`, plus `timeoutSeconds` and `pollIntervalMs` for the wait. For
+full control, `request(kind, options)` is the single call behind them (it
+answers within `wait` seconds, 0 to 25), and `poll(id)` also returns `result`
+and `expired`.
+
 ## Handling failure
 
 ```js
@@ -119,7 +163,10 @@ reported separately rather than collapsed into one flag.
 | `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 |
+| `request(kind, options?)` | Ask for `"location"` or `"photo"`; `title`, `message`, `requireBiometric`, `priority`, `wait`, `expiresIn` |
+| `requestLocation(options?)` | Ask for a position and wait, past the 25s cap, on one request |
+| `requestPhoto(options?)` | Ask for one picture and wait, past the 25s cap |
+| `poll(id)` | Ask about an approval or request already started (carries `result` and `expired`) |
 | `ask(question, options?)` | `requestApproval()` reduced to a boolean |
 
 `priority` runs `-2` to `2`. **`2` is the only level that crosses quiet
@@ -133,7 +180,7 @@ 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
+The whole client is `fetch` against a few documented endpoints. If you would
 rather not add a dependency, this is the entire integration:
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lauther-client",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Send push notifications to your phone from any web app or script — and ask questions that wait for a yes.",
   "keywords": [
     "push",

package/src/index.d.ts

@@ -69,6 +69,13 @@ export interface PollResult {
   response: "approve" | "deny" | null;
   /** How the answer was confirmed, e.g. a biometric check. `null` if not. */
   confirmedBy: string | null;
+  /**
+   * What a request carried back: a `LocationResult` or `PhotoResult` once
+   * approved, `null` until then, when denied, and for plain approvals.
+   */
+  result?: LocationResult | PhotoResult | null;
+  /** `true` once a request has lapsed unanswered; there is no point polling on. */
+  expired?: boolean;
 }
 
 export interface WaitOptions extends Omit<ApproveOptions, "title" | "wait"> {
@@ -90,6 +97,73 @@ export interface ApprovalOutcome {
   waitedSeconds: number;
 }
 
+/** The kinds of thing a person can be asked to share. */
+export type RequestKind = "location" | "photo";
+
+export interface RequestOptions {
+  /** The question. Defaults to "Share your location?" / "Take a photo?". */
+  title?: string;
+  message?: string;
+  /** Demand a fingerprint or face before the share goes out. */
+  requireBiometric?: boolean;
+  priority?: Priority;
+  /** Seconds to wait for an answer, 0-25. Defaults to 25. */
+  wait?: number;
+  /** Seconds the request stays answerable, 60-3600. Defaults to 600. */
+  expiresIn?: number;
+}
+
+/** One position, as the phone read it a moment before sending. */
+export interface LocationResult {
+  lat: number;
+  lng: number;
+  /** Metres. Absent when the phone did not report one. */
+  accuracy?: number;
+  /** ISO 8601 time of the reading. */
+  at: string;
+}
+
+/** One picture. Shared photos are kept for 7 days, then deleted. */
+export interface PhotoResult {
+  /** Download link for the JPEG. */
+  url: string;
+  bytes: number;
+  width?: number;
+  height?: number;
+}
+
+export interface RequestResult {
+  ok: true;
+  id: string;
+  /** `null` means nobody answered in time. Silence is not consent. */
+  response: "approve" | "deny" | null;
+  /** What was shared. `null` unless the person approved. */
+  result: LocationResult | PhotoResult | null;
+}
+
+export interface RequestWaitOptions extends Omit<RequestOptions, "wait"> {
+  /**
+   * How long to wait in total, in seconds. The server long-polls for the
+   * first 25s; beyond that the client polls the same request, so the person
+   * still sees exactly one.
+   */
+  timeoutSeconds?: number;
+  /** Gap between polls once past the server's 25s window. Defaults to 3000. */
+  pollIntervalMs?: number;
+}
+
+export interface RequestOutcome<R = LocationResult | PhotoResult> {
+  id: string;
+  /** `null` means nobody answered, or the request expired. */
+  response: "approve" | "deny" | null;
+  confirmedBy: string | null;
+  /** What was shared. `null` unless `response` is `"approve"`. */
+  result: R | null;
+  waitedSeconds: number;
+  /** `true` when the request lapsed on the phone before anyone answered. */
+  expired: boolean;
+}
+
 export interface LautherOptions {
   baseUrl?: string;
   fetch?: typeof globalThis.fetch;
@@ -117,6 +191,12 @@ export declare class Lauther {
   poll(id: string): Promise<PollResult>;
   /** Ask and wait, past the server's 25s cap, on one notification. */
   requestApproval(question: string, options?: WaitOptions): Promise<ApprovalOutcome>;
+  /** Ask the person to share `"location"` or a `"photo"`; answers within `wait` seconds. */
+  request(kind: RequestKind, options?: RequestOptions): Promise<RequestResult>;
+  /** Ask for the person's position and wait, past the server's 25s cap. */
+  requestLocation(options?: RequestWaitOptions): Promise<RequestOutcome<LocationResult>>;
+  /** Ask for one picture and wait, past the server's 25s cap. */
+  requestPhoto(options?: RequestWaitOptions): Promise<RequestOutcome<PhotoResult>>;
   /** True only on an explicit Approve; a denial and a timeout are both false. */
   ask(question: string, options?: WaitOptions): Promise<boolean>;
 }

package/src/index.js

@@ -2,7 +2,7 @@
  * 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
+ * Zero dependencies on purpose. The whole client is `fetch` against a few
  * 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.
@@ -116,7 +116,10 @@ export class Lauther {
    * 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()`.
+   * For a request, the answer also carries `result` (what was shared, or
+   * `null`) and `expired` (true once the request has lapsed unanswered).
+   *
+   * @param {string} id The `id` returned by `approve()` or `request()`.
    * @returns {Promise<import("./index.d.ts").PollResult>}
    */
   async poll(id) {
@@ -176,6 +179,110 @@ export class Lauther {
     };
   }
 
+  /**
+   * Ask the person to share something from their phone: where they are, or a
+   * picture. The "yes" carries the payload.
+   *
+   * Like `approve()` this blocks server-side for up to 25 seconds, and
+   * `response` is `"approve"`, `"deny"` or `null`. On an approve, `result`
+   * holds what was shared (see `LocationResult` and `PhotoResult`); on
+   * anything else it is `null`.
+   *
+   * @param {"location" | "photo"} kind
+   * @param {import("./index.d.ts").RequestOptions} [options]
+   * @returns {Promise<import("./index.d.ts").RequestResult>}
+   */
+  async request(kind, options) {
+    if (!kind) {
+      throw new LautherError('request() needs a kind: "location" or "photo".');
+    }
+    const {wait = MAX_WAIT_SECONDS, ...rest} = options ?? {};
+    return this.#request("/v1/request", {
+      kind,
+      ...rest,
+      wait: Math.min(Math.max(Number(wait) || 0, 0), MAX_WAIT_SECONDS),
+    });
+  }
+
+  /**
+   * Ask for the person's position, once, and wait for the answer as long as
+   * you are willing. Same waiting rules as `requestApproval()`: one request
+   * on the phone, polled past the server's 25s cap, never thrown on timeout.
+   *
+   * @param {import("./index.d.ts").RequestWaitOptions} [options]
+   * @returns {Promise<import("./index.d.ts").RequestOutcome<import("./index.d.ts").LocationResult>>}
+   */
+  requestLocation(options = {}) {
+    return this.#requestAndWait("location", options);
+  }
+
+  /**
+   * Ask for one picture and wait for it. Same waiting rules as
+   * `requestApproval()`. `result.url` is a download link that expires after
+   * 7 days.
+   *
+   * @param {import("./index.d.ts").RequestWaitOptions} [options]
+   * @returns {Promise<import("./index.d.ts").RequestOutcome<import("./index.d.ts").PhotoResult>>}
+   */
+  requestPhoto(options = {}) {
+    return this.#requestAndWait("photo", options);
+  }
+
+  /**
+   * Shared by `requestLocation()` and `requestPhoto()`: start the request,
+   * then keep asking about the SAME notification until it is answered,
+   * expires, or `timeoutSeconds` runs out.
+   *
+   * @param {"location" | "photo"} kind
+   * @param {import("./index.d.ts").RequestWaitOptions} options
+   */
+  async #requestAndWait(kind, options) {
+    const {
+      timeoutSeconds = MAX_WAIT_SECONDS,
+      pollIntervalMs = 3000,
+      ...rest
+    } = options ?? {};
+    const startedAt = Date.now();
+    const elapsed = () => (Date.now() - startedAt) / 1000;
+
+    const started = await this.request(kind, {
+      ...rest,
+      wait: Math.min(timeoutSeconds, MAX_WAIT_SECONDS),
+    });
+    if (started.response) {
+      return {
+        id: started.id, response: started.response,
+        confirmedBy: started.confirmedBy ?? null, result: started.result ?? null,
+        waitedSeconds: Math.round(elapsed()), expired: false,
+      };
+    }
+
+    while (elapsed() < timeoutSeconds) {
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+      const {response, confirmedBy, result, expired} = await this.poll(started.id);
+      if (response) {
+        return {
+          id: started.id, response, confirmedBy: confirmedBy ?? null,
+          result: result ?? null, waitedSeconds: Math.round(elapsed()),
+          expired: false,
+        };
+      }
+      // The request lapsed on the phone: nothing more can arrive, so stop
+      // waiting rather than idling out the rest of the timeout.
+      if (expired === true) {
+        return {
+          id: started.id, response: null, confirmedBy: null, result: null,
+          waitedSeconds: Math.round(elapsed()), expired: true,
+        };
+      }
+    }
+    // Nobody answered. As with requestApproval(): an outcome, not an error.
+    return {
+      id: started.id, response: null, confirmedBy: null, result: null,
+      waitedSeconds: Math.round(elapsed()), expired: false,
+    };
+  }
+
   /**
    * `requestApproval()` reduced to a boolean, for the common `if` around
    * something irreversible.