@mythryl/app-sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mythryl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @mythryl/app-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The browser SDK for Mythryl mini apps. It connects an app to the Mythryl window that embeds it.
+
+```sh
+npm install @mythryl/app-sdk
+```
+
+```ts
+import sdk from "@mythryl/app-sdk";
+
+await sdk.ready();
+
+const context = await sdk.getContext();
+console.log(context.user.handle);
+```
+
+The default export is created on first use, so importing it has no side effects and is safe in code that also renders
+on the server. Call it from effects and event handlers, which run in the browser.
+
+## API
+
+| Call | Result |
+| --- | --- |
+| `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.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`. |
+
+### 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.
+
+### Signing in to your server
+
+`sdk.auth.signin()` returns a token valid for 10 minutes, issued for the app's domain. Send it to your server as a
+bearer token and verify it there with [`@mythryl/server-sdk`](https://www.npmjs.com/package/@mythryl/server-sdk). The SDK
+caches the token and requests a new one when less than a minute of validity remains; `signin({ force: true })` always
+requests a new one.
+
+```ts
+const { token } = await sdk.auth.signin();
+
+const headers = { authorization: `Bearer ${token}` };
+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 that gets no answer within 30 seconds rejects with `unavailable`.
+
+## Outside a host
+
+Outside a Mythryl window there is no host to answer, and calls time out. `isEmbedded()` returns whether the page is
+framed:
+
+```ts
+import sdk, { isEmbedded } from "@mythryl/app-sdk";
+
+if (isEmbedded()) await sdk.ready();
+```
+
+## Other transports
+
+`createSdk(transport)` builds an SDK over any `Transport`, which is how the SDK runs in a webview or a test. The default
+export uses `windowTransport()`, which talks to the embedding window.
+
+## License
+
+MIT

package/dist/channel.d.ts

@@ -0,0 +1,11 @@
+import { type EventName, type Events, type MethodName, type Methods } from "@mythryl/protocol";
+import type { Transport } from "./transport.js";
+export interface Channel {
+    /** Sends a call. Resolves with the result, or rejects with a `ProtocolError`. */
+    request: <M extends MethodName>(method: M, params: Methods[M]["params"], version: number) => Promise<Methods[M]["result"]>;
+    subscribe: <E extends EventName>(event: E, listener: (data: Events[E]) => void) => () => void;
+    /** Removes the transport listener and rejects pending calls with `cancelled`. */
+    dispose: () => void;
+}
+/** Correlates responses with requests by id, enforces the call timeout and dispatches events. Independent of which calls exist. */
+export declare const createChannel: (transport: Transport, timeoutMs?: number) => Channel;

package/dist/channel.js

@@ -0,0 +1,55 @@
+import { CALL_TIMEOUT_MS, MESSAGE_SOURCE, ProtocolError, isEventMessage, isResponseMessage, } from "@mythryl/protocol";
+/** Correlates responses with requests by id, enforces the call timeout and dispatches events. Independent of which calls exist. */
+export const createChannel = (transport, timeoutMs = CALL_TIMEOUT_MS) => {
+    const pending = new Map();
+    const listeners = new Map();
+    let lastId = 0;
+    const stopListening = transport.listen((data) => {
+        if (isResponseMessage(data))
+            pending.get(data.id)?.settle(data);
+        else if (isEventMessage(data))
+            listeners.get(data.event)?.forEach((listener) => listener(data.data));
+    });
+    return {
+        request: (method, params, version) => new Promise((resolve, reject) => {
+            const id = String((lastId += 1));
+            const done = () => {
+                clearTimeout(timer);
+                pending.delete(id);
+            };
+            const timer = setTimeout(() => {
+                done();
+                reject(new ProtocolError("unavailable", `${method} did not answer in ${timeoutMs} ms.`));
+            }, timeoutMs);
+            pending.set(id, {
+                timer,
+                fail: (error) => {
+                    done();
+                    reject(error);
+                },
+                settle: (response) => {
+                    done();
+                    // The result is cast without validation: the host returns the type declared for the method.
+                    if (response.ok)
+                        resolve(response.result);
+                    else
+                        reject(new ProtocolError(response.error.code, response.error.message));
+                },
+            });
+            transport.post({ source: MESSAGE_SOURCE, v: version, type: "request", id, method, params });
+        }),
+        subscribe: (event, listener) => {
+            const forEvent = (data) => listener(data);
+            const set = listeners.get(event) ?? new Set();
+            set.add(forEvent);
+            listeners.set(event, set);
+            return () => void set.delete(forEvent);
+        },
+        dispose: () => {
+            stopListening();
+            listeners.clear();
+            for (const call of [...pending.values()])
+                call.fail(new ProtocolError("cancelled", "The SDK was disposed."));
+        },
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/** Default SDK instance. Communicates with the window that embeds the app and is created on first call. */
+declare const sdk: import("./sdk.js").Sdk;
+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";

package/dist/index.js

@@ -0,0 +1,9 @@
+import { lazySdk } from "./lazy.js";
+import { createSdk } from "./sdk.js";
+/** Default SDK instance. Communicates with the window that embeds the app and is created on first call. */
+const sdk = lazySdk(() => createSdk());
+export default sdk;
+export { sdk };
+export { createSdk } from "./sdk.js";
+export { isEmbedded, windowTransport } from "./transport.js";
+export { EVENT_NAMES, ProtocolError } from "@mythryl/protocol";

package/dist/jwt-expiry.d.ts

@@ -0,0 +1,2 @@
+/** Returns the `exp` claim of a JWT in milliseconds, or `undefined` if it is absent or unreadable. The signature is not verified. */
+export declare const expiryOf: (token: string) => number | undefined;

package/dist/jwt-expiry.js

@@ -0,0 +1,13 @@
+/** Returns the `exp` claim of a JWT in milliseconds, or `undefined` if it is absent or unreadable. The signature is not verified. */
+export const expiryOf = (token) => {
+    const payload = token.split(".")[1];
+    if (!payload)
+        return undefined;
+    try {
+        const { exp } = JSON.parse(atob(payload.replace(/-/g, "+").replace(/_/g, "/")));
+        return typeof exp === "number" ? exp * 1000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/lazy.d.ts

@@ -0,0 +1,6 @@
+import type { Sdk } from "./sdk.js";
+/**
+ * Wraps an SDK so that it is created on first use. Importing the wrapper has no side effects, so it is safe where no
+ * `window` exists (server rendering, builds). After `dispose()`, the next call creates a new instance.
+ */
+export declare const lazySdk: (create: () => Sdk) => Sdk;

package/dist/lazy.js

@@ -0,0 +1,20 @@
+/**
+ * Wraps an SDK so that it is created on first use. Importing the wrapper has no side effects, so it is safe where no
+ * `window` exists (server rendering, builds). After `dispose()`, the next call creates a new instance.
+ */
+export const lazySdk = (create) => {
+    let current;
+    const sdk = () => (current ??= create());
+    return {
+        ready: () => sdk().ready(),
+        close: () => sdk().close(),
+        getCapabilities: () => sdk().getCapabilities(),
+        getContext: () => sdk().getContext(),
+        auth: { signin: (options) => sdk().auth.signin(options) },
+        on: (event, listener) => sdk().on(event, listener),
+        dispose: () => {
+            current?.dispose();
+            current = undefined;
+        },
+    };
+};

package/dist/sdk.d.ts

@@ -0,0 +1,36 @@
+import { type AppContext, type Capability, type EventName, type Events } from "@mythryl/protocol";
+import { type Transport } from "./transport.js";
+export interface Sdk {
+    /** Signals that the app has loaded. The host removes its loading screen. */
+    ready: () => Promise<void>;
+    /** Closes the app. */
+    close: () => Promise<void>;
+    /** Returns the capabilities the host supports. Check before calling optional features. */
+    getCapabilities: () => Promise<readonly Capability[]>;
+    getContext: () => Promise<AppContext>;
+    auth: {
+        /**
+         * Returns a token that authenticates the person 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
+         * minute of validity remains.
+         *
+         * @param options.force Skip the cache and request a new token.
+         */
+        signin: (options?: {
+            force?: boolean;
+        }) => Promise<{
+            token: string;
+        }>;
+    };
+    /** Subscribes to a host event. Returns a function that removes the listener. */
+    on: <E extends EventName>(event: E, listener: (data: Events[E]) => void) => () => void;
+    /** Removes listeners and rejects pending calls with `cancelled`. */
+    dispose: () => void;
+}
+/**
+ * Creates an SDK over a transport. The first call performs the `hello` handshake, which selects the protocol version.
+ * Later calls use the selected version.
+ */
+export declare const createSdk: (transport?: Transport) => Sdk;

package/dist/sdk.js

@@ -0,0 +1,35 @@
+import { LATEST_VERSION, SUPPORTED_VERSIONS, } from "@mythryl/protocol";
+import { createChannel } from "./channel.js";
+import { createTokenCache } from "./token-cache.js";
+import { windowTransport } from "./transport.js";
+/**
+ * Creates an SDK over a transport. The first call performs the `hello` handshake, which selects the protocol version.
+ * Later calls use the selected version.
+ */
+export const createSdk = (transport = windowTransport()) => {
+    const channel = createChannel(transport);
+    let handshake;
+    // A failed handshake is discarded, so the next call retries it.
+    const connect = () => {
+        handshake ??= channel.request("hello", { versions: SUPPORTED_VERSIONS }, LATEST_VERSION).catch((error) => {
+            handshake = undefined;
+            throw error;
+        });
+        return handshake;
+    };
+    const call = async (method, params) => channel.request(method, params, (await connect()).version);
+    const tokens = createTokenCache(() => call("auth.signin", undefined));
+    return {
+        ready: () => call("ready", undefined),
+        close: () => call("close", undefined),
+        getCapabilities: async () => (await connect()).capabilities,
+        getContext: () => call("getContext", undefined),
+        auth: { signin: (options) => tokens.get(options?.force) },
+        // The host sends events only after the handshake, so subscribing starts it.
+        on: (event, listener) => {
+            connect().catch(() => undefined);
+            return channel.subscribe(event, listener);
+        },
+        dispose: channel.dispose,
+    };
+};

package/dist/token-cache.d.ts

@@ -0,0 +1,10 @@
+export interface TokenCache {
+    /** Returns the cached token while it has more than a minute of validity left, otherwise requests a new one. `force` skips the cache. */
+    get: (force?: boolean) => Promise<{
+        token: string;
+    }>;
+}
+/** Caches the most recent token until shortly before it expires. Concurrent calls share a single request. */
+export declare const createTokenCache: (fetchToken: () => Promise<{
+    token: string;
+}>, now?: () => number) => TokenCache;

package/dist/token-cache.js

@@ -0,0 +1,28 @@
+import { expiryOf } from "./jwt-expiry.js";
+/** Time in milliseconds before expiry at which a cached token is replaced. */
+const REFRESH_BEFORE_MS = 60_000;
+/** Caches the most recent token until shortly before it expires. Concurrent calls share a single request. */
+export const createTokenCache = (fetchToken, now = Date.now) => {
+    let cached;
+    let pending;
+    const request = () => {
+        pending ??= fetchToken()
+            .then(({ token }) => {
+            // A token without an `exp` claim is returned but not cached.
+            const expiresAt = expiryOf(token);
+            cached = expiresAt === undefined ? undefined : { token, expiresAt };
+            return { token };
+        })
+            .finally(() => {
+            pending = undefined;
+        });
+        return pending;
+    };
+    return {
+        get: async (force = false) => {
+            if (!force && cached && cached.expiresAt - now() > REFRESH_BEFORE_MS)
+                return { token: cached.token };
+            return request();
+        },
+    };
+};

package/dist/transport.d.ts

@@ -0,0 +1,14 @@
+import type { Message } from "@mythryl/protocol";
+/** Message transport between the app and the host. The SDK depends only on this interface, so it runs unchanged over a frame, a webview or a test double. */
+export interface Transport {
+    post: (message: Message) => void;
+    /** Registers a handler for incoming data, passed unvalidated. Returns a function that removes the handler. */
+    listen: (handler: (data: unknown) => void) => () => void;
+}
+/** Returns whether the page is embedded in a host frame. Outside a frame there is no host to talk to. */
+export declare const isEmbedded: () => boolean;
+/**
+ * Transport over `postMessage` with the embedding window. Accepts messages only from that window. The host origin is
+ * not known in advance, so outgoing messages use the `*` target origin and must not contain secrets.
+ */
+export declare const windowTransport: (host?: Window) => Transport;

package/dist/transport.js

@@ -0,0 +1,17 @@
+/** Returns whether the page is embedded in a host frame. Outside a frame there is no host to talk to. */
+export const isEmbedded = () => window.parent !== window;
+/**
+ * Transport over `postMessage` with the embedding window. Accepts messages only from that window. The host origin is
+ * not known in advance, so outgoing messages use the `*` target origin and must not contain secrets.
+ */
+export const windowTransport = (host = window.parent) => ({
+    post: (message) => host.postMessage(message, "*"),
+    listen: (handler) => {
+        const onMessage = (event) => {
+            if (event.source === host)
+                handler(event.data);
+        };
+        window.addEventListener("message", onMessage);
+        return () => window.removeEventListener("message", onMessage);
+    },
+});

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@mythryl/app-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The browser SDK for Mythryl mini apps.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mythryl-studio/mythryl-sdk.git",
+    "directory": "packages/app-sdk"
+  },
+  "keywords": [
+    "mythryl",
+    "mini-apps",
+    "sdk"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@mythryl/protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.3",
+    "vitest": "^5.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }