lauther-client 0.3.0 → 0.4.0

package/README.md

@@ -84,7 +84,8 @@ const { response } = await lauther.approve({
 
 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.
+home on the answer. Three kinds: where they are, one picture, and a short
+typed answer.
 
 ```js
 const where = await lauther.requestLocation({
@@ -105,7 +106,18 @@ if (shot.response === "approve") {
 }
 ```
 
-Both return `{ id, response, confirmedBy, result, waitedSeconds, expired }`.
+```js
+const code = await lauther.requestText({
+  title: "What is the 6-digit code from your authenticator?",
+  placeholder: "6-digit code",
+});
+
+if (code.response === "approve") {
+  const { text } = code.result; // what they typed
+}
+```
+
+All three 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.
@@ -117,9 +129,14 @@ means the request lapsed on the phone (10 minutes by default; set
   `{ 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
+- **Text** is a short answer they type on the phone: `{ text }`, 1 to 500
+  characters. Use it for a code, a choice, a short fact only they know. The
+  optional `placeholder` (up to 80 characters) hints at the shape of the
+  answer, such as "6-digit code".
+
+Options for all three: `title`, `message`, `requireBiometric`, `priority`,
+`expiresIn`, plus `timeoutSeconds` and `pollIntervalMs` for the wait;
+`requestText()` also takes `placeholder`. 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`.
@@ -163,9 +180,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 |
-| `request(kind, options?)` | Ask for `"location"` or `"photo"`; `title`, `message`, `requireBiometric`, `priority`, `wait`, `expiresIn` |
+| `request(kind, options?)` | Ask for `"location"`, `"photo"` or `"text"`; `title`, `message`, `requireBiometric`, `priority`, `wait`, `expiresIn`, `placeholder` |
 | `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 |
+| `requestText(options?)` | Ask a short question and wait for the typed answer, 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 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lauther-client",
-  "version": "0.3.0",
+  "version": "0.4.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

@@ -70,10 +70,10 @@ export interface PollResult {
   /** 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.
+   * What a request carried back: a `LocationResult`, `PhotoResult` or
+   * `TextResult` once approved, `null` until then, when denied, and for plain approvals.
    */
-  result?: LocationResult | PhotoResult | null;
+  result?: LocationResult | PhotoResult | TextResult | null;
   /** `true` once a request has lapsed unanswered; there is no point polling on. */
   expired?: boolean;
 }
@@ -98,10 +98,13 @@ export interface ApprovalOutcome {
 }
 
 /** The kinds of thing a person can be asked to share. */
-export type RequestKind = "location" | "photo";
+export type RequestKind = "location" | "photo" | "text";
 
 export interface RequestOptions {
-  /** The question. Defaults to "Share your location?" / "Take a photo?". */
+  /**
+   * The question. Defaults to "Share your location?" / "Take a photo?" /
+   * "Answer a question?".
+   */
   title?: string;
   message?: string;
   /** Demand a fingerprint or face before the share goes out. */
@@ -111,6 +114,11 @@ export interface RequestOptions {
   wait?: number;
   /** Seconds the request stays answerable, 60-3600. Defaults to 600. */
   expiresIn?: number;
+  /**
+   * Text requests only: a hint at the shape of the answer, shown in the
+   * field on the phone ("6-digit code"). Up to 80 characters.
+   */
+  placeholder?: string;
 }
 
 /** One position, as the phone read it a moment before sending. */
@@ -132,13 +140,18 @@ export interface PhotoResult {
   height?: number;
 }
 
+/** A typed answer: 1 to 500 characters, trimmed. */
+export interface TextResult {
+  text: string;
+}
+
 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;
+  result: LocationResult | PhotoResult | TextResult | null;
 }
 
 export interface RequestWaitOptions extends Omit<RequestOptions, "wait"> {
@@ -152,7 +165,7 @@ export interface RequestWaitOptions extends Omit<RequestOptions, "wait"> {
   pollIntervalMs?: number;
 }
 
-export interface RequestOutcome<R = LocationResult | PhotoResult> {
+export interface RequestOutcome<R = LocationResult | PhotoResult | TextResult> {
   id: string;
   /** `null` means nobody answered, or the request expired. */
   response: "approve" | "deny" | null;
@@ -191,12 +204,14 @@ 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. */
+  /** Ask the person to share `"location"`, a `"photo"` or a typed `"text"`; 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>>;
+  /** Ask a short question and wait for the typed answer, past the server's 25s cap. */
+  requestText(options?: RequestWaitOptions): Promise<RequestOutcome<TextResult>>;
   /** 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

@@ -180,21 +180,21 @@ export class Lauther {
   }
 
   /**
-   * Ask the person to share something from their phone: where they are, or a
-   * picture. The "yes" carries the payload.
+   * Ask the person to share something from their phone: where they are, a
+   * picture, or a short typed answer. 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`.
+   * holds what was shared (see `LocationResult`, `PhotoResult` and
+   * `TextResult`); on anything else it is `null`.
    *
-   * @param {"location" | "photo"} kind
+   * @param {"location" | "photo" | "text"} 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".');
+      throw new LautherError('request() needs a kind: "location", "photo" or "text".');
     }
     const {wait = MAX_WAIT_SECONDS, ...rest} = options ?? {};
     return this.#request("/v1/request", {
@@ -229,11 +229,24 @@ export class Lauther {
   }
 
   /**
-   * Shared by `requestLocation()` and `requestPhoto()`: start the request,
-   * then keep asking about the SAME notification until it is answered,
-   * expires, or `timeoutSeconds` runs out.
+   * Ask a short question and wait for the typed answer: a code, a name, a
+   * choice. Same waiting rules as `requestApproval()`. `options.placeholder`
+   * (up to 80 characters) hints at the shape of the answer on the phone, for
+   * example "6-digit code". `result.text` is 1 to 500 characters.
    *
-   * @param {"location" | "photo"} kind
+   * @param {import("./index.d.ts").RequestWaitOptions} [options]
+   * @returns {Promise<import("./index.d.ts").RequestOutcome<import("./index.d.ts").TextResult>>}
+   */
+  requestText(options = {}) {
+    return this.#requestAndWait("text", options);
+  }
+
+  /**
+   * Shared by `requestLocation()`, `requestPhoto()` and `requestText()`:
+   * start the request, then keep asking about the SAME notification until it
+   * is answered, expires, or `timeoutSeconds` runs out.
+   *
+   * @param {"location" | "photo" | "text"} kind
    * @param {import("./index.d.ts").RequestWaitOptions} options
    */
   async #requestAndWait(kind, options) {