@reset-framework/sdk 1.0.2 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reset-framework/sdk",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "type": "module",
   "description": "Browser-side SDK for Reset Framework applications.",
   "license": "MIT",

package/src/client.js

@@ -62,6 +62,45 @@ function requireNumberField(record, field, command) {
   return value
 }
 
+function optionalStringField(record, field, fallback, command) {
+  const value = record[field]
+
+  if (value === undefined || value === null) {
+    return fallback
+  }
+
+  if (typeof value !== "string") {
+    throw new ResetProtocolError(
+      `Reset runtime returned an invalid '${field}' field for '${command}'.`,
+      { command }
+    )
+  }
+
+  return value
+}
+
+function normalizeStringArray(value, field, command) {
+  if (!Array.isArray(value)) {
+    throw new ResetProtocolError(
+      `Reset runtime returned an invalid '${field}' field for '${command}'.`,
+      { command }
+    )
+  }
+
+  return Object.freeze(
+    value.map((entry) => {
+      if (typeof entry !== "string") {
+        throw new ResetProtocolError(
+          `Reset runtime returned an invalid '${field}' field for '${command}'.`,
+          { command }
+        )
+      }
+
+      return entry
+    })
+  )
+}
+
 function normalizeAppInfo(payload, command) {
   const record = requireObject(payload, command)
 
@@ -97,6 +136,63 @@ function normalizeCapabilities(payload, command) {
   })
 }
 
+function normalizeProtocolLaunch(payload, command) {
+  const record = requireObject(payload, command)
+
+  return Object.freeze({
+    id: requireStringField(record, "id", command),
+    url: requireStringField(record, "url", command),
+    scheme: requireStringField(record, "scheme", command),
+    host: optionalStringField(record, "host", "", command),
+    path: optionalStringField(record, "path", "", command),
+    query: optionalStringField(record, "query", "", command),
+    fragment: optionalStringField(record, "fragment", "", command),
+    source: requireStringField(record, "source", command),
+    coldStart: requireBooleanField(record, "coldStart", command)
+  })
+}
+
+function normalizeProtocolLaunchEnvelope(payload, command) {
+  const record = requireObject(payload, command)
+  const launch = record.launch
+
+  if (launch === null) {
+    return null
+  }
+
+  return normalizeProtocolLaunch(launch, command)
+}
+
+function normalizeProtocolLaunchList(payload, command) {
+  const record = requireObject(payload, command)
+  const launches = record.launches
+
+  if (!Array.isArray(launches)) {
+    throw new ResetProtocolError(
+      `Reset runtime returned an invalid 'launches' field for '${command}'.`,
+      { command }
+    )
+  }
+
+  return Object.freeze(launches.map((entry) => normalizeProtocolLaunch(entry, command)))
+}
+
+function normalizeProtocolInfo(payload, command) {
+  const record = requireObject(payload, command)
+
+  return Object.freeze({
+    supported: requireBooleanField(record, "supported", command),
+    module: requireStringField(record, "module", command),
+    platform: requireStringField(record, "platform", command),
+    configuredSchemes: normalizeStringArray(record.configuredSchemes ?? [], "configuredSchemes", command),
+    bundledSchemes: normalizeStringArray(record.bundledSchemes ?? [], "bundledSchemes", command),
+    eventName: requireStringField(record, "eventName", command),
+    pendingCount: requireNumberField(record, "pendingCount", command),
+    eventStreamActive: requireBooleanField(record, "eventStreamActive", command),
+    runtimeRegistration: requireBooleanField(record, "runtimeRegistration", command)
+  })
+}
+
 function createCommandApi(transport) {
   return Object.freeze({
     invoke(command, payload = {}) {
@@ -524,10 +620,68 @@ function createShortcutApi(transport) {
   })
 }
 
-function createProtocolApi(transport) {
+function createProtocolApi(transport, events) {
   return Object.freeze({
-    getInfo() {
-      return transport.invoke("protocol.getInfo")
+    async getInfo() {
+      return normalizeProtocolInfo(await transport.invoke("protocol.getInfo"), "protocol.getInfo")
+    },
+    async activate() {
+      const payload = requireObject(await transport.invoke("protocol.activate"), "protocol.activate")
+      return Object.freeze({
+        active: requireBooleanField(payload, "active", "protocol.activate")
+      })
+    },
+    async getCurrentLaunch() {
+      return normalizeProtocolLaunchEnvelope(
+        await transport.invoke("protocol.getCurrentLaunch"),
+        "protocol.getCurrentLaunch"
+      )
+    },
+    async getPendingLaunches() {
+      return normalizeProtocolLaunchList(
+        await transport.invoke("protocol.getPendingLaunches"),
+        "protocol.getPendingLaunches"
+      )
+    },
+    async consumePendingLaunches() {
+      return normalizeProtocolLaunchList(
+        await transport.invoke("protocol.consumePendingLaunches"),
+        "protocol.consumePendingLaunches"
+      )
+    },
+    async listen(handler, options = {}) {
+      if (typeof handler !== "function") {
+        throw new TypeError("Reset protocol listener must be a function.")
+      }
+
+      const consumePending = options.consumePending !== false
+      const seenLaunches = new Set()
+      const deliver = (payload) => {
+        const launch = normalizeProtocolLaunch(payload, "protocol.open")
+        if (seenLaunches.has(launch.id)) {
+          return
+        }
+
+        seenLaunches.add(launch.id)
+        handler(launch)
+      }
+
+      const dispose = events.listen("protocol.open", deliver)
+      await transport.invoke("protocol.activate")
+
+      if (consumePending) {
+        const pending = await transport.invoke("protocol.consumePendingLaunches")
+        for (const launch of normalizeProtocolLaunchList(pending, "protocol.consumePendingLaunches")) {
+          if (seenLaunches.has(launch.id)) {
+            continue
+          }
+
+          seenLaunches.add(launch.id)
+          handler(launch)
+        }
+      }
+
+      return dispose
     },
     register(options = {}) {
       return transport.invoke("protocol.register", options)
@@ -585,7 +739,7 @@ export function createResetClient(source) {
   const menu = createMenuApi(transport)
   const tray = createTrayApi(transport)
   const shortcut = createShortcutApi(transport)
-  const protocol = createProtocolApi(transport)
+  const protocol = createProtocolApi(transport, events)
   const updater = createUpdaterApi(transport)
   const net = createNetApi(transport)
 

package/src/index.d.ts

@@ -382,8 +382,37 @@ export interface ResetShortcutApi {
   unregisterAll(): Promise<unknown>;
 }
 
+export interface ResetProtocolLaunch {
+  id: string;
+  url: string;
+  scheme: string;
+  host: string;
+  path: string;
+  query: string;
+  fragment: string;
+  source: string;
+  coldStart: boolean;
+}
+
+export interface ResetProtocolInfo extends ResetSupportInfo {
+  configuredSchemes: ReadonlyArray<string>;
+  bundledSchemes: ReadonlyArray<string>;
+  eventName: string;
+  pendingCount: number;
+  eventStreamActive: boolean;
+  runtimeRegistration: boolean;
+}
+
 export interface ResetProtocolApi {
-  getInfo(): Promise<ResetSupportInfo>;
+  getInfo(): Promise<ResetProtocolInfo>;
+  activate(): Promise<{ active: boolean }>;
+  getCurrentLaunch(): Promise<ResetProtocolLaunch | null>;
+  getPendingLaunches(): Promise<ReadonlyArray<ResetProtocolLaunch>>;
+  consumePendingLaunches(): Promise<ReadonlyArray<ResetProtocolLaunch>>;
+  listen(
+    handler: (launch: ResetProtocolLaunch) => void,
+    options?: { consumePending?: boolean }
+  ): Promise<() => void>;
   register(options?: {
     scheme?: string;
   }): Promise<unknown>;