@mythryl/app-sdk 0.1.1 → 0.1.3

package/README.md

@@ -27,13 +27,38 @@ on the server. Call it from effects and event handlers, which run in the browser
 | `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.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.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.follow(did)` | Asks the person to follow an account. Rejects with `cancelled` if they decline. |
+| `sdk.share()` | Opens the share sheet with a link to the app. |
 | `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 `share` 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`) is confirmed by the person. 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. `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.
+`minimised` and `maximised` are sent when the person 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.
+
+### Light and dark mode
+
+`sdk.getContext()` returns the host's current mode in `client.colorScheme`, and the `colorSchemeChanged` event reports
+each change. What the app does with it is up to the app.
+
+```ts
+const { client } = await sdk.getContext();
+setMode(client.colorScheme);
+
+sdk.on("colorSchemeChanged", setMode);
+```
 
 ### Signing in to your server
 

package/dist/index.d.ts

@@ -4,4 +4,4 @@ export default sdk;
 export { sdk };
 export { createSdk, type Sdk } from "./sdk.js";
 export { isEmbedded, windowTransport, type Transport } from "./transport.js";
-export { EVENT_NAMES, ProtocolError, type AppContext, type Capability, type ErrorCode, type EventName, type Events } from "@mythryl/protocol";
+export { EVENT_NAMES, ProtocolError, type AppContext, type Capability, type ColorScheme, type ErrorCode, type EventName, type Events, } from "@mythryl/protocol";

package/dist/index.js

@@ -6,4 +6,4 @@ export default sdk;
 export { sdk };
 export { createSdk } from "./sdk.js";
 export { isEmbedded, windowTransport } from "./transport.js";
-export { EVENT_NAMES, ProtocolError } from "@mythryl/protocol";
+export { EVENT_NAMES, ProtocolError, } from "@mythryl/protocol";

package/dist/lazy.js

@@ -11,6 +11,14 @@ export const lazySdk = (create) => {
         getCapabilities: () => sdk().getCapabilities(),
         getContext: () => sdk().getContext(),
         auth: { signin: (options) => sdk().auth.signin(options) },
+        openProfile: (actor) => sdk().openProfile(actor),
+        openPost: (uri) => sdk().openPost(uri),
+        openTopic: (slug) => sdk().openTopic(slug),
+        openUrl: (url) => sdk().openUrl(url),
+        openApp: (options) => sdk().openApp(options),
+        compose: (options) => sdk().compose(options),
+        follow: (did) => sdk().follow(did),
+        share: () => sdk().share(),
         on: (event, listener) => sdk().on(event, listener),
         dispose: () => {
             current?.dispose();

package/dist/sdk.d.ts

@@ -25,6 +25,30 @@ 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. */
+    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. */
+    openUrl: (url: string) => Promise<void>;
+    /** Opens another mini app by its domain and closes this one. `url` is where in that app to start, on its own domain. */
+    openApp: (options: {
+        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. */
+    compose: (options?: {
+        text?: string;
+        embedUrl?: string;
+    }) => Promise<{
+        uri?: string;
+    }>;
+    /** Asks the person to follow an account, by DID. Rejects with `cancelled` if they decline. Needs the `follow` capability. */
+    follow: (did: string) => Promise<void>;
+    /** Opens the share sheet with a link to the app. Needs the `share` capability. */
+    share: () => Promise<void>;
     on: <E extends EventName>(event: E, listener: (data: Events[E]) => void) => () => void;
     /** Removes listeners and rejects pending calls with `cancelled`. */
     dispose: () => void;

package/dist/sdk.js

@@ -25,6 +25,14 @@ export const createSdk = (transport = windowTransport()) => {
         getCapabilities: async () => (await connect()).capabilities,
         getContext: () => call("getContext", undefined),
         auth: { signin: (options) => tokens.get(options?.force) },
+        openProfile: (actor) => call("openProfile", { actor }),
+        openPost: (uri) => call("openPost", { uri }),
+        openTopic: (slug) => call("openTopic", { slug }),
+        openUrl: (url) => call("openUrl", { url }),
+        openApp: (options) => call("openApp", options),
+        compose: (options) => call("compose", options ?? {}),
+        follow: (did) => call("follow", { did }),
+        share: () => call("share", 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.1",
+  "version": "0.1.3",
   "description": "The browser SDK for Mythryl mini apps.",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,7 @@
     }
   },
   "dependencies": {
-    "@mythryl/protocol": "0.1.1"
+    "@mythryl/protocol": "0.1.3"
   },
   "devDependencies": {
     "typescript": "~6.0.3",