@mythryl/app-sdk 0.1.5 → 0.1.7

package/README.md

@@ -25,27 +25,28 @@ on the server. Call it from effects and event handlers, which run in the browser
 | `sdk.ready()` | Signals that the app has loaded. The host removes its loading screen. |
 | `sdk.close()` | Closes the app. |
 | `sdk.getCapabilities()` | The capabilities the host supports. Check before calling optional features. |
-| `sdk.getContext()` | The signed-in person, how the app was launched, and the client environment. |
-| `sdk.auth.signin({ force? })` | `{ token }`: a JWT that authenticates the person to the app's own server. |
+| `sdk.getContext()` | The signed-in user, how the app was launched, and the client environment. |
+| `sdk.auth.signin({ force? })` | `{ token }`: a JWT that authenticates the user to the app's own server. |
 | `sdk.openProfile(actor)` | Opens a profile (handle or DID) in the host and minimises the app. |
 | `sdk.openPost(uri)` | Opens a post, by its `at://` URI, and minimises the app. |
 | `sdk.openTopic(slug)` | Opens a topic, by name without the slash, and minimises the app. |
-| `sdk.openUrl(url)` | Opens an `https` address in the browser once the person confirms. Rejects with `cancelled` if they decline. |
+| `sdk.openUrl(url)` | Opens an `https` address in the browser once the user confirms. Rejects with `cancelled` if they decline. |
 | `sdk.openStorePage(domain?)` | Opens an app's store page in the host and minimises this app. Without a domain, it is this app's own page. |
 | `sdk.openApp({ domain, url? })` | Opens another mini app and closes this one. `url` is where to start, on that app's domain. |
-| `sdk.compose({ text?, embedUrl? })` | Opens the composer with a draft. `{ uri }` if the person posted, `{}` if they did not. |
-| `sdk.install()` | Asks the person to add this app to their library. Resolves at once if it is already there; rejects with `cancelled` if they decline. |
-| `sdk.follow(did)` | Asks the person to follow an account. Rejects with `cancelled` if they decline. |
+| `sdk.compose({ text?, embedUrl? })` | Opens the composer with a draft. `{ uri }` if the user posted, `{}` if they did not. |
+| `sdk.notifications.request()` | Asks the user to let the app notify them, adding it to their library too. On yes, Mythryl sends your server a notification token for the user (the `notifications.enabled` webhook). Resolves at once if they are already on; rejects with `cancelled` if they decline. |
+| `sdk.install()` | Asks the user to add this app to their library. Resolves at once if it is already there; rejects with `cancelled` if they decline. |
+| `sdk.follow(did)` | Asks the user to follow an account. Rejects with `cancelled` if they decline. |
 | `sdk.on(event, listener)` | Subscribes to a host event. Returns a function that removes the listener. |
 | `sdk.dispose()` | Removes listeners and rejects pending calls with `cancelled`. |
 
-`openProfile`, `openPost`, `openTopic`, `openUrl` and `openApp` need the `navigation` capability. `compose`, `follow` and `install`
+`openProfile`, `openPost`, `openTopic`, `openUrl` and `openApp` need the `navigation` capability. `compose`, `follow`, `install` and `notifications.request`
 each have a capability of the same name. Older hosts have none of them: check `sdk.getCapabilities()`
-first, or handle the `unsupported` rejection. Anything that writes (`compose`, `follow`, `install`) is confirmed by the person. A target the host cannot open rejects with `unavailable`.
+first, or handle the `unsupported` rejection. Anything that writes (`compose`, `follow`, `install`, `notifications.request`) is confirmed by the user. A target the host cannot open rejects with `unavailable`.
 
 ### Events
 
-`minimised` and `maximised` are sent when the person hides the app and brings it back. `colorSchemeChanged` is sent with
+`minimised` and `maximised` are sent when the user hides the app and brings it back. `colorSchemeChanged` is sent with
 `"light"` or `"dark"` when the host switches mode. `closing` and `resized` are defined by the protocol; hosts do not send
 them yet. `closing` is best effort and must not be relied on to save state.
 
@@ -78,7 +79,7 @@ const response = await fetch("/api/me", { headers });
 ### Errors
 
 A call that fails rejects with a `ProtocolError`. Its `code` is `cancelled`, `unsupported`, `not_consented`,
-`rate_limited` or `unavailable`. A call the host answers by itself that gets no answer within 30 seconds rejects with `unavailable`. A call that waits on the person (`openUrl`, `openApp`, `compose`, `follow`, `install`) has no time limit: it ends when they answer.
+`rate_limited` or `unavailable`. A call the host answers by itself that gets no answer within 30 seconds rejects with `unavailable`. A call that waits on the user (`openUrl`, `openApp`, `compose`, `follow`, `install`, `notifications.request`) has no time limit: it ends when they answer.
 
 ## Outside a host
 

package/dist/channel.d.ts

@@ -8,7 +8,7 @@ export interface Channel {
     dispose: () => void;
 }
 /**
- * Correlates responses with requests by id, enforces the call timeout and dispatches events. A call that waits on a person
- * has no timeout (`WAITS_ON_PERSON`): it ends when they answer or the SDK is disposed.
+ * Correlates responses with requests by id, enforces the call timeout and dispatches events. A call that waits on a user
+ * has no timeout (`WAITS_ON_USER`): it ends when they answer or the SDK is disposed.
  */
 export declare const createChannel: (transport: Transport, timeoutMs?: number) => Channel;

package/dist/channel.js

@@ -1,7 +1,7 @@
-import { CALL_TIMEOUT_MS, MESSAGE_SOURCE, ProtocolError, isEventMessage, isResponseMessage, WAITS_ON_PERSON, } from "@mythryl/protocol";
+import { CALL_TIMEOUT_MS, MESSAGE_SOURCE, ProtocolError, isEventMessage, isResponseMessage, WAITS_ON_USER, } from "@mythryl/protocol";
 /**
- * Correlates responses with requests by id, enforces the call timeout and dispatches events. A call that waits on a person
- * has no timeout (`WAITS_ON_PERSON`): it ends when they answer or the SDK is disposed.
+ * Correlates responses with requests by id, enforces the call timeout and dispatches events. A call that waits on a user
+ * has no timeout (`WAITS_ON_USER`): it ends when they answer or the SDK is disposed.
  */
 export const createChannel = (transport, timeoutMs = CALL_TIMEOUT_MS) => {
     const pending = new Map();
@@ -21,7 +21,7 @@ export const createChannel = (transport, timeoutMs = CALL_TIMEOUT_MS) => {
                     clearTimeout(timer);
                 pending.delete(id);
             };
-            const timer = WAITS_ON_PERSON[method]
+            const timer = WAITS_ON_USER[method]
                 ? undefined
                 : setTimeout(() => {
                     done();

package/dist/lazy.js

@@ -20,6 +20,7 @@ export const lazySdk = (create) => {
         compose: (options) => sdk().compose(options),
         follow: (did) => sdk().follow(did),
         install: () => sdk().install(),
+        notifications: { request: () => sdk().notifications.request() },
         on: (event, listener) => sdk().on(event, listener),
         dispose: () => {
             current?.dispose();

package/dist/sdk.d.ts

@@ -10,7 +10,7 @@ export interface Sdk {
     getContext: () => Promise<AppContext>;
     auth: {
         /**
-         * Returns a token that authenticates the person to the app's own server.
+         * Returns a token that authenticates the user to the app's own server.
          *
          * The token is a JWT signed by Mythryl. Its `aud` is the app's domain and it is valid for 10 minutes. Send it as a
          * bearer token and verify it on the server. The SDK caches the token and requests a new one when less than a
@@ -25,13 +25,13 @@ export interface Sdk {
         }>;
     };
     /** Subscribes to a host event. Returns a function that removes the listener. */
-    /** Opens a person's profile in the host and minimises the app. `actor` is a handle or a DID. Check the `navigation` capability first. */
+    /** Opens a user's profile in the host and minimises the app. `actor` is a handle or a DID. Check the `navigation` capability first. */
     openProfile: (actor: string) => Promise<void>;
     /** Opens a post in the host and minimises the app. `uri` is the post's `at://` URI. */
     openPost: (uri: string) => Promise<void>;
     /** Opens a topic in the host and minimises the app. `slug` is the topic's name without the leading slash. */
     openTopic: (slug: string) => Promise<void>;
-    /** Opens an `https` address in the browser after the person confirms. Rejects with `cancelled` if they decline. */
+    /** Opens an `https` address in the browser after the user confirms. Rejects with `cancelled` if they decline. */
     openUrl: (url: string) => Promise<void>;
     /** Opens an app's store page in the host and minimises the calling app. `domain` names the app; left out, it is this app's own page. */
     openStorePage: (domain?: string) => Promise<void>;
@@ -40,16 +40,24 @@ export interface Sdk {
         domain: string;
         url?: string;
     }) => Promise<void>;
-    /** Opens the composer with a draft. Resolves with the post's URI if the person posted, and without one if they did not. Needs the `compose` capability. */
+    /** Opens the composer with a draft. Resolves with the post's URI if the user posted, and without one if they did not. Needs the `compose` capability. */
     compose: (options?: {
         text?: string;
         embedUrl?: string;
     }) => Promise<{
         uri?: string;
     }>;
-    /** Asks the person to add this app to their library. Resolves at once if it is already there; rejects with `cancelled` if they decline. Needs the `install` capability. */
+    /** Asks the user to add this app to their library. Resolves at once if it is already there; rejects with `cancelled` if they decline. Needs the `install` capability. */
     install: () => Promise<void>;
-    /** Asks the person to follow an account, by DID. Rejects with `cancelled` if they decline. Needs the `follow` capability. */
+    notifications: {
+        /**
+         * Asks the user to let the app notify them, which also adds it to their library. On yes, Mythryl sends your server a
+         * notification token for the user (the `notifications.enabled` webhook). Resolves at once if they are already on;
+         * rejects with `cancelled` if they decline. Needs the `notifications` capability.
+         */
+        request: () => Promise<void>;
+    };
+    /** Asks the user to follow an account, by DID. Rejects with `cancelled` if they decline. Needs the `follow` capability. */
     follow: (did: string) => Promise<void>;
     on: <E extends EventName>(event: E, listener: (data: Events[E]) => void) => () => void;
     /** Removes listeners and rejects pending calls with `cancelled`. */

package/dist/sdk.js

@@ -34,6 +34,7 @@ export const createSdk = (transport = windowTransport()) => {
         compose: (options) => call("compose", options ?? {}),
         follow: (did) => call("follow", { did }),
         install: () => call("install", undefined),
+        notifications: { request: () => call("notifications.request", undefined) },
         // The host sends events only after the handshake, so subscribing starts it.
         on: (event, listener) => {
             connect().catch(() => undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mythryl/app-sdk",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "The browser SDK for Mythryl mini apps.",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,7 @@
     }
   },
   "dependencies": {
-    "@mythryl/protocol": "0.1.5"
+    "@mythryl/protocol": "0.1.7"
   },
   "devDependencies": {
     "typescript": "~6.0.3",