@reset-framework/sdk 0.2.0 → 0.2.1

package/README.md

@@ -4,7 +4,7 @@
 
 Responsibilities:
 
-- expose a stable `invoke()` API for app frontends
+- expose a stable typed client for app frontends
 - hide the raw `window.reset` bridge envelope
 - provide runtime availability checks for local browser development
 - centralize the shared browser helpers used by templates and demo apps
@@ -12,5 +12,30 @@ Responsibilities:
 Package layout:
 
 - `src/index.js`: public entrypoint
-- `src/client.js`: runtime bridge helpers
+- `src/client.js`: high-level client and namespaced APIs
+- `src/transport.js`: low-level transport and response validation
 - `src/errors.js`: SDK-specific error types
+
+Recommended usage:
+
+```ts
+import { reset } from "@reset-framework/sdk"
+
+const appInfo = await reset.app.getInfo()
+const runtimeInfo = await reset.runtime.getInfo()
+```
+
+Available namespaces:
+
+- `reset.app.getId()`
+- `reset.app.getName()`
+- `reset.app.getSlug()`
+- `reset.app.getVersion()`
+- `reset.app.getInfo()`
+- `reset.runtime.getPlatform()`
+- `reset.runtime.getArchitecture()`
+- `reset.runtime.getFrameworkVersion()`
+- `reset.runtime.getBridgeVersion()`
+- `reset.runtime.getInfo()`
+- `reset.commands.invoke()`
+- `reset.commands.invokeRaw()`

package/package.json

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

package/src/client.js

@@ -1,53 +1,170 @@
-import { ResetRuntimeUnavailableError } from "./errors.js"
+import {
+  createResetTransport,
+  getResetRuntime,
+  invoke,
+  invokeRaw,
+  isResetRuntimeAvailable
+} from "./transport.js"
+import { ResetProtocolError } from "./errors.js"
 
-function getDefaultWindowTarget() {
-  if (typeof window === "undefined") {
-    return undefined
+function isObjectLike(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function requireObject(value, command) {
+  if (!isObjectLike(value)) {
+    throw new ResetProtocolError(
+      `Reset runtime returned an invalid payload for '${command}'.`,
+      { command }
+    )
   }
 
-  return window
+  return value
 }
 
-export function isResetRuntimeAvailable(target = getDefaultWindowTarget()) {
-  return Boolean(
-    target &&
-      target.reset &&
-      typeof target.reset.invoke === "function"
-  )
-}
+function requireStringField(record, field, command) {
+  const value = record[field]
 
-export function getResetRuntime(target = getDefaultWindowTarget()) {
-  if (!isResetRuntimeAvailable(target)) {
-    throw new ResetRuntimeUnavailableError()
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new ResetProtocolError(
+      `Reset runtime returned an invalid '${field}' field for '${command}'.`,
+      { command }
+    )
   }
 
-  return target.reset
+  return value
 }
 
-export async function invokeRaw(command, payload = {}, target = getDefaultWindowTarget()) {
-  return getResetRuntime(target).invoke(command, payload)
+function requireBooleanField(record, field, command) {
+  const value = record[field]
+
+  if (typeof value !== "boolean") {
+    throw new ResetProtocolError(
+      `Reset runtime returned an invalid '${field}' field for '${command}'.`,
+      { command }
+    )
+  }
+
+  return value
 }
 
-export async function invoke(command, payload = {}, target = getDefaultWindowTarget()) {
-  const response = await invokeRaw(command, payload, target)
+function normalizeAppInfo(payload, command) {
+  const record = requireObject(payload, command)
 
-  if (!response.ok) {
-    throw new Error(response.error)
-  }
+  return Object.freeze({
+    id: requireStringField(record, "id", command),
+    name: requireStringField(record, "name", command),
+    slug: requireStringField(record, "slug", command),
+    version: requireStringField(record, "version", command),
+    windowTitle: requireStringField(record, "windowTitle", command)
+  })
+}
+
+function normalizeRuntimeInfo(payload, command) {
+  const record = requireObject(payload, command)
 
-  return response.result
+  return Object.freeze({
+    platform: requireStringField(record, "platform", command),
+    arch: requireStringField(record, "arch", command),
+    frameworkVersion: requireStringField(record, "frameworkVersion", command),
+    bridgeVersion: requireStringField(record, "bridgeVersion", command),
+    debug: requireBooleanField(record, "debug", command)
+  })
 }
 
-export function createResetClient(target = getDefaultWindowTarget()) {
-  return {
-    isAvailable() {
-      return isResetRuntimeAvailable(target)
-    },
+function createCommandApi(transport) {
+  return Object.freeze({
     invoke(command, payload = {}) {
-      return invoke(command, payload, target)
+      return transport.invoke(command, payload)
     },
     invokeRaw(command, payload = {}) {
-      return invokeRaw(command, payload, target)
+      return transport.invokeRaw(command, payload)
     }
-  }
+  })
+}
+
+function createAppApi(transport) {
+  return Object.freeze({
+    async getId() {
+      const payload = requireObject(await transport.invoke("app.getId"), "app.getId")
+      return requireStringField(payload, "id", "app.getId")
+    },
+    async getName() {
+      const payload = requireObject(await transport.invoke("app.getName"), "app.getName")
+      return requireStringField(payload, "name", "app.getName")
+    },
+    async getSlug() {
+      const payload = requireObject(await transport.invoke("app.getSlug"), "app.getSlug")
+      return requireStringField(payload, "slug", "app.getSlug")
+    },
+    async getVersion() {
+      const payload = requireObject(await transport.invoke("app.getVersion"), "app.getVersion")
+      return requireStringField(payload, "version", "app.getVersion")
+    },
+    async getInfo() {
+      return normalizeAppInfo(await transport.invoke("app.getInfo"), "app.getInfo")
+    }
+  })
+}
+
+function createRuntimeApi(transport) {
+  return Object.freeze({
+    async getPlatform() {
+      const payload = requireObject(await transport.invoke("runtime.getPlatform"), "runtime.getPlatform")
+      return requireStringField(payload, "platform", "runtime.getPlatform")
+    },
+    async getArchitecture() {
+      const payload = requireObject(await transport.invoke("runtime.getArchitecture"), "runtime.getArchitecture")
+      return requireStringField(payload, "arch", "runtime.getArchitecture")
+    },
+    async getFrameworkVersion() {
+      const payload = requireObject(
+        await transport.invoke("runtime.getFrameworkVersion"),
+        "runtime.getFrameworkVersion"
+      )
+      return requireStringField(payload, "version", "runtime.getFrameworkVersion")
+    },
+    async getBridgeVersion() {
+      const payload = requireObject(
+        await transport.invoke("runtime.getBridgeVersion"),
+        "runtime.getBridgeVersion"
+      )
+      return requireStringField(payload, "version", "runtime.getBridgeVersion")
+    },
+    async getInfo() {
+      return normalizeRuntimeInfo(await transport.invoke("runtime.getInfo"), "runtime.getInfo")
+    }
+  })
 }
+
+export function createResetClient(source) {
+  const transport = createResetTransport(source)
+  const commands = createCommandApi(transport)
+  const app = createAppApi(transport)
+  const runtime = createRuntimeApi(transport)
+
+  return Object.freeze({
+    isAvailable() {
+      return transport.isAvailable()
+    },
+    getRuntime() {
+      return transport.getRuntime()
+    },
+    commands,
+    app,
+    runtime
+  })
+}
+
+export {
+  createResetTransport,
+  getResetRuntime,
+  invoke,
+  invokeRaw,
+  isResetRuntimeAvailable
+} from "./transport.js"
+
+export const reset = createResetClient()
+export const commands = reset.commands
+export const app = reset.app
+export const runtime = reset.runtime

package/src/errors.js

@@ -1,6 +1,31 @@
-export class ResetRuntimeUnavailableError extends Error {
-  constructor(message = "reset runtime is not available") {
+export class ResetRuntimeError extends Error {
+  constructor(message, options = {}) {
     super(message)
-    this.name = "ResetRuntimeUnavailableError"
+    this.name = new.target.name
+
+    if ("cause" in options) {
+      this.cause = options.cause
+    }
+  }
+}
+
+export class ResetRuntimeUnavailableError extends ResetRuntimeError {
+  constructor(message = "Reset runtime is not available in the current environment.") {
+    super(message)
+  }
+}
+
+export class ResetProtocolError extends ResetRuntimeError {
+  constructor(message, options = {}) {
+    super(message, options)
+    this.command = options.command
+  }
+}
+
+export class ResetInvocationError extends ResetRuntimeError {
+  constructor(command, message, response, options = {}) {
+    super(message, options)
+    this.command = command
+    this.response = response
   }
 }

package/src/index.d.ts

@@ -12,6 +12,10 @@ export type ResetInvokeResponse<T = unknown> =
   | ResetInvokeSuccess<T>
   | ResetInvokeError;
 
+export type ResetPlatform = "macos" | "windows" | "linux" | "unknown";
+
+export type ResetArchitecture = "arm64" | "x64" | "x86" | "unknown";
+
 export interface ResetRuntime {
   invoke<T = unknown>(
     command: string,
@@ -23,39 +27,133 @@ export interface ResetRuntimeWindow {
   reset?: ResetRuntime;
 }
 
+export interface ResetRuntimeSourceOptions {
+  target?: ResetRuntimeWindow;
+  runtime?: ResetRuntime;
+  resolveRuntime?: () => ResetRuntime | undefined;
+}
+
+export type ResetRuntimeSource =
+  | ResetRuntime
+  | ResetRuntimeWindow
+  | ResetRuntimeSourceOptions
+  | (() => ResetRuntime | undefined)
+  | undefined;
+
+export interface ResetTransport {
+  isAvailable(): boolean;
+  getRuntime(): ResetRuntime;
+  invokeRaw<T = unknown>(
+    command: string,
+    payload?: unknown
+  ): Promise<ResetInvokeResponse<T>>;
+  invoke<T = unknown>(command: string, payload?: unknown): Promise<T>;
+}
+
+export interface ResetCommandApi {
+  invoke<T = unknown>(command: string, payload?: unknown): Promise<T>;
+  invokeRaw<T = unknown>(
+    command: string,
+    payload?: unknown
+  ): Promise<ResetInvokeResponse<T>>;
+}
+
+export interface ResetAppInfo {
+  id: string;
+  name: string;
+  slug: string;
+  version: string;
+  windowTitle: string;
+}
+
+export interface ResetRuntimeInfo {
+  platform: ResetPlatform;
+  arch: ResetArchitecture;
+  frameworkVersion: string;
+  bridgeVersion: string;
+  debug: boolean;
+}
+
+export interface ResetAppApi {
+  getId(): Promise<string>;
+  getName(): Promise<string>;
+  getSlug(): Promise<string>;
+  getVersion(): Promise<string>;
+  getInfo(): Promise<ResetAppInfo>;
+}
+
+export interface ResetRuntimeApi {
+  getPlatform(): Promise<ResetPlatform>;
+  getArchitecture(): Promise<ResetArchitecture>;
+  getFrameworkVersion(): Promise<string>;
+  getBridgeVersion(): Promise<string>;
+  getInfo(): Promise<ResetRuntimeInfo>;
+}
+
+export interface ResetClient {
+  isAvailable(): boolean;
+  getRuntime(): ResetRuntime;
+  commands: ResetCommandApi;
+  app: ResetAppApi;
+  runtime: ResetRuntimeApi;
+}
+
 declare global {
   interface Window extends ResetRuntimeWindow {}
 }
 
-export class ResetRuntimeUnavailableError extends Error {
+export class ResetRuntimeError extends Error {
+  cause?: unknown;
+  constructor(message?: string, options?: { cause?: unknown });
+}
+
+export class ResetRuntimeUnavailableError extends ResetRuntimeError {
   constructor(message?: string);
 }
 
+export class ResetProtocolError extends ResetRuntimeError {
+  command?: string;
+  constructor(message?: string, options?: { command?: string; cause?: unknown });
+}
+
+export class ResetInvocationError extends ResetRuntimeError {
+  command: string;
+  response: ResetInvokeError;
+  constructor(
+    command: string,
+    message: string,
+    response: ResetInvokeError,
+    options?: { cause?: unknown }
+  );
+}
+
 export function isResetRuntimeAvailable(
-  target?: ResetRuntimeWindow
+  source?: ResetRuntimeSource
 ): boolean;
 
 export function getResetRuntime(
-  target?: ResetRuntimeWindow
+  source?: ResetRuntimeSource
 ): ResetRuntime;
 
+export function createResetTransport(
+  source?: ResetRuntimeSource
+): ResetTransport;
+
 export function invokeRaw<T = unknown>(
   command: string,
   payload?: unknown,
-  target?: ResetRuntimeWindow
+  source?: ResetRuntimeSource
 ): Promise<ResetInvokeResponse<T>>;
 
 export function invoke<T = unknown>(
   command: string,
   payload?: unknown,
-  target?: ResetRuntimeWindow
+  source?: ResetRuntimeSource
 ): Promise<T>;
 
-export function createResetClient(target?: ResetRuntimeWindow): {
-  isAvailable(): boolean;
-  invoke<T = unknown>(command: string, payload?: unknown): Promise<T>;
-  invokeRaw<T = unknown>(
-    command: string,
-    payload?: unknown
-  ): Promise<ResetInvokeResponse<T>>;
-};
+export function createResetClient(source?: ResetRuntimeSource): ResetClient;
+
+export const reset: ResetClient;
+export const commands: ResetCommandApi;
+export const app: ResetAppApi;
+export const runtime: ResetRuntimeApi;

package/src/index.js

@@ -1,9 +1,19 @@
 export {
+  app,
+  commands,
   createResetClient,
+  createResetTransport,
   getResetRuntime,
   invoke,
   invokeRaw,
-  isResetRuntimeAvailable
+  isResetRuntimeAvailable,
+  reset,
+  runtime
 } from "./client.js"
 
-export { ResetRuntimeUnavailableError } from "./errors.js"
+export {
+  ResetInvocationError,
+  ResetProtocolError,
+  ResetRuntimeError,
+  ResetRuntimeUnavailableError
+} from "./errors.js"

package/src/transport.js

@@ -0,0 +1,162 @@
+import {
+  ResetInvocationError,
+  ResetProtocolError,
+  ResetRuntimeUnavailableError
+} from "./errors.js"
+
+function getDefaultWindowTarget() {
+  if (typeof window === "undefined") {
+    return undefined
+  }
+
+  return window
+}
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+function isObjectLike(value) {
+  return typeof value === "object" && value !== null
+}
+
+function isRuntimeLike(value) {
+  return isObjectLike(value) && typeof value.invoke === "function"
+}
+
+function createTargetRuntimeResolver(target) {
+  return () => {
+    if (!isObjectLike(target) || !isRuntimeLike(target.reset)) {
+      return undefined
+    }
+
+    return target.reset
+  }
+}
+
+function normalizeRuntimeResolver(source) {
+  if (source === undefined) {
+    return () => {
+      const target = getDefaultWindowTarget()
+      return isObjectLike(target) && isRuntimeLike(target.reset) ? target.reset : undefined
+    }
+  }
+
+  if (typeof source === "function") {
+    return () => {
+      const runtime = source()
+      return isRuntimeLike(runtime) ? runtime : undefined
+    }
+  }
+
+  if (isRuntimeLike(source)) {
+    return () => source
+  }
+
+  if (isObjectLike(source) && (hasOwn(source, "runtime") || hasOwn(source, "resolveRuntime") || hasOwn(source, "target"))) {
+    if (typeof source.resolveRuntime === "function") {
+      return () => {
+        const runtime = source.resolveRuntime()
+        return isRuntimeLike(runtime) ? runtime : undefined
+      }
+    }
+
+    if (isRuntimeLike(source.runtime)) {
+      return () => source.runtime
+    }
+
+    return createTargetRuntimeResolver(source.target)
+  }
+
+  return createTargetRuntimeResolver(source)
+}
+
+function assertCommand(command) {
+  if (typeof command !== "string" || command.trim() === "") {
+    throw new TypeError("Reset command must be a non-empty string.")
+  }
+}
+
+function normalizeResponse(command, response) {
+  if (!isObjectLike(response) || typeof response.ok !== "boolean") {
+    throw new ResetProtocolError(
+      `Reset runtime returned an invalid response envelope for '${command}'.`,
+      { command }
+    )
+  }
+
+  if (response.ok === false) {
+    if (typeof response.error !== "string" || response.error.trim() === "") {
+      throw new ResetProtocolError(
+        `Reset runtime returned an invalid error response for '${command}'.`,
+        { command }
+      )
+    }
+
+    return Object.freeze({
+      ok: false,
+      error: response.error
+    })
+  }
+
+  return Object.freeze({
+    ok: true,
+    result: response.result
+  })
+}
+
+function resolveRuntimeOrThrow(resolveRuntime) {
+  const runtime = resolveRuntime()
+
+  if (!isRuntimeLike(runtime)) {
+    throw new ResetRuntimeUnavailableError()
+  }
+
+  return runtime
+}
+
+export function isResetRuntimeAvailable(source) {
+  return isRuntimeLike(normalizeRuntimeResolver(source)())
+}
+
+export function getResetRuntime(source) {
+  return resolveRuntimeOrThrow(normalizeRuntimeResolver(source))
+}
+
+export async function invokeRaw(command, payload = {}, source) {
+  assertCommand(command)
+
+  const runtime = resolveRuntimeOrThrow(normalizeRuntimeResolver(source))
+  const response = await runtime.invoke(command, payload)
+
+  return normalizeResponse(command, response)
+}
+
+export async function invoke(command, payload = {}, source) {
+  const response = await invokeRaw(command, payload, source)
+
+  if (!response.ok) {
+    throw new ResetInvocationError(command, response.error, response)
+  }
+
+  return response.result
+}
+
+export function createResetTransport(source) {
+  const resolveRuntime = normalizeRuntimeResolver(source)
+
+  return Object.freeze({
+    isAvailable() {
+      return isRuntimeLike(resolveRuntime())
+    },
+    getRuntime() {
+      return resolveRuntimeOrThrow(resolveRuntime)
+    },
+    invokeRaw(command, payload = {}) {
+      return invokeRaw(command, payload, resolveRuntime)
+    },
+    invoke(command, payload = {}) {
+      return invoke(command, payload, resolveRuntime)
+    }
+  })
+}