@frockbot/mobile-core 0.0.0 → 0.1.0

package/package.json

@@ -1,14 +1,28 @@
 {
   "name": "@frockbot/mobile-core",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "cordis": "4.0.0-rc.8"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/mobile-core"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/index.test.ts

@@ -0,0 +1,158 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { Context } from "cordis";
+import { decodeMobileShareRequest, MobileCommandRegistry } from "./index.js";
+
+const roots: Context[] = [];
+
+async function createRegistry(): Promise<Context> {
+  const root = new Context();
+  roots.push(root);
+  await root.plugin(MobileCommandRegistry);
+  return root;
+}
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => root.fiber.dispose()));
+});
+
+async function expectFailure(
+  promise: Promise<unknown>,
+  message: string,
+): Promise<void> {
+  let failure: unknown;
+  try {
+    await promise;
+  } catch (error) {
+    failure = error;
+  }
+  expect(failure).toBeInstanceOf(Error);
+  expect(failure instanceof Error ? failure.message : "").toContain(message);
+}
+
+describe("MobileCommandRegistry", () => {
+  test("decodes and invokes a registered command", async () => {
+    const root = await createRegistry();
+    root.mobileCommands.register({
+      id: "fixture.echo",
+      decode(input: unknown): string {
+        if (typeof input !== "string") throw new Error("text is required");
+        return input;
+      },
+      execute: (input: string) => Promise.resolve(`echo:${input}`),
+    });
+
+    expect(
+      await root.mobileCommands.invoke<string>("fixture.echo", "hello"),
+    ).toBe("echo:hello");
+    await expectFailure(
+      root.mobileCommands.invoke("fixture.echo", { text: "no" }),
+      "text is required",
+    );
+  });
+
+  test("removes only the registration that owns the command", async () => {
+    const root = await createRegistry();
+    const dispose = root.mobileCommands.register({
+      id: "fixture.command",
+      decode: () => null,
+      execute: () => Promise.resolve(),
+    });
+
+    expect(root.mobileCommands.list()).toEqual([{ id: "fixture.command" }]);
+    dispose();
+    dispose();
+    expect(root.mobileCommands.list()).toEqual([]);
+    await expectFailure(
+      root.mobileCommands.invoke("fixture.command", null),
+      'mobile command "fixture.command" is unavailable',
+    );
+  });
+
+  test("rejects duplicate command ids", async () => {
+    const root = await createRegistry();
+    const first = {
+      id: "fixture.command",
+      decode: () => null,
+      execute: () => Promise.resolve(),
+    };
+    root.mobileCommands.register(first);
+
+    expect(() => root.mobileCommands.register(first)).toThrow(
+      'mobile command "fixture.command" is already registered',
+    );
+  });
+
+  test("rejects an empty command id", async () => {
+    const root = await createRegistry();
+
+    expect(() =>
+      root.mobileCommands.register({
+        id: "  ",
+        decode: () => null,
+        execute: () => Promise.resolve(),
+      }),
+    ).toThrow("mobile command id must not be empty");
+  });
+
+  test("lists registered commands in sorted order", async () => {
+    const root = await createRegistry();
+    root.mobileCommands.register({
+      id: "fixture.second",
+      decode: () => null,
+      execute: () => Promise.resolve(),
+    });
+    root.mobileCommands.register({
+      id: "fixture.first",
+      decode: () => null,
+      execute: () => Promise.resolve(),
+    });
+
+    expect(root.mobileCommands.list()).toEqual([
+      { id: "fixture.first" },
+      { id: "fixture.second" },
+    ]);
+  });
+
+  test("honors cancellation before execution", async () => {
+    const root = await createRegistry();
+    let executions = 0;
+    root.mobileCommands.register({
+      id: "fixture.cancelled",
+      decode: () => null,
+      execute: () => {
+        executions += 1;
+        return Promise.resolve();
+      },
+    });
+    const controller = new AbortController();
+    controller.abort(new Error("cancelled by test"));
+
+    await expectFailure(
+      root.mobileCommands.invoke("fixture.cancelled", null, controller.signal),
+      "cancelled by test",
+    );
+    expect(executions).toBe(0);
+  });
+});
+
+describe("decodeMobileShareRequest", () => {
+  test("normalizes a share request that carries text", () => {
+    expect(
+      decodeMobileShareRequest({ title: " Turn ", text: " done ", url: " " }),
+    ).toEqual({ title: "Turn", text: "done", url: undefined });
+  });
+
+  test("requires an exact request carrying text or url", () => {
+    expect(() => decodeMobileShareRequest({ title: "Turn" })).toThrow(
+      "share request must include text or url",
+    );
+    expect(() =>
+      decodeMobileShareRequest({ text: "done", extra: true }),
+    ).toThrow("share request has unknown fields");
+    const hidden = { text: "done" };
+    Object.defineProperty(hidden, "secret", { value: true });
+    expect(() => decodeMobileShareRequest(hidden)).toThrow(
+      "share request has unknown fields",
+    );
+  });
+});

package/src/index.ts

@@ -0,0 +1,177 @@
+import { type Context, Service } from "cordis";
+
+export interface MobileCommandContext {
+  signal: AbortSignal;
+}
+
+export type MobileCommandPayload = object | string | number | boolean | null;
+export type MobileCommandResult = MobileCommandPayload | void;
+
+export interface MobileCommand<
+  Input extends MobileCommandPayload,
+  Output extends MobileCommandResult,
+> {
+  id: string;
+  decode(input: unknown): Input;
+  execute(input: Input, context: MobileCommandContext): Promise<Output>;
+}
+
+interface RegisteredMobileCommand {
+  source: object;
+  decode(input: unknown): MobileCommandPayload;
+  execute(
+    input: MobileCommandPayload,
+    context: MobileCommandContext,
+  ): Promise<MobileCommandResult>;
+}
+
+export interface MobileCommandSummary {
+  id: string;
+}
+
+export class MobileCommandRegistry extends Service {
+  private commands = new Map<string, RegisteredMobileCommand>();
+
+  constructor(ctx: Context) {
+    super(ctx, "mobileCommands");
+  }
+
+  register<
+    Input extends MobileCommandPayload,
+    Output extends MobileCommandResult,
+  >(command: MobileCommand<Input, Output>): () => void {
+    const id = command.id.trim();
+    if (!id) throw new Error("mobile command id must not be empty");
+    if (this.commands.has(id)) {
+      throw new Error(`mobile command "${id}" is already registered`);
+    }
+    const registered: RegisteredMobileCommand = {
+      source: command,
+      decode: (input) => command.decode(input),
+      execute: (input, context) => command.execute(input as Input, context),
+    };
+    this.commands.set(id, registered);
+    return () => {
+      if (this.commands.get(id)?.source === command) this.commands.delete(id);
+    };
+  }
+
+  list(): MobileCommandSummary[] {
+    return [...this.commands.keys()].sort().map((id) => ({ id }));
+  }
+
+  async invoke<Output extends MobileCommandResult = MobileCommandResult>(
+    commandId: string,
+    input: unknown,
+    signal: AbortSignal = new AbortController().signal,
+  ): Promise<Output> {
+    const command = this.commands.get(commandId);
+    if (!command) {
+      throw new Error(`mobile command "${commandId}" is unavailable`);
+    }
+    signal.throwIfAborted();
+    const decoded = command.decode(input);
+    signal.throwIfAborted();
+    return (await command.execute(decoded, { signal })) as Output;
+  }
+}
+
+export type MobileNotificationUrgency = "normal" | "critical";
+
+export interface MobileNotificationRequest {
+  title: string;
+  body?: string;
+  urgency: MobileNotificationUrgency;
+}
+
+export abstract class MobileNotificationCapability extends Service {
+  constructor(ctx: Context) {
+    super(ctx, "mobileNotifications");
+  }
+
+  abstract show(
+    request: MobileNotificationRequest,
+    signal: AbortSignal,
+  ): Promise<void>;
+}
+
+export abstract class MobileClipboardCapability extends Service {
+  constructor(ctx: Context) {
+    super(ctx, "mobileClipboard");
+  }
+
+  abstract readText(signal: AbortSignal): Promise<string>;
+
+  abstract writeText(text: string, signal: AbortSignal): Promise<void>;
+}
+
+export interface MobileShareRequest {
+  title?: string;
+  text?: string;
+  url?: string;
+}
+
+function exactObject(
+  input: unknown,
+  allowedKeys: readonly string[],
+  label: string,
+): Record<string, unknown> {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const keys = Reflect.ownKeys(input);
+  if (
+    keys.some(
+      (key) =>
+        typeof key !== "string" ||
+        !allowedKeys.includes(key) ||
+        !Object.prototype.propertyIsEnumerable.call(input, key),
+    )
+  ) {
+    throw new Error(`${label} has unknown fields`);
+  }
+  return input as Record<string, unknown>;
+}
+
+function optionalShareField(
+  record: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const value = record[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string") throw new Error(`${key} must be a string`);
+  const normalized = value.trim();
+  return normalized ? normalized : undefined;
+}
+
+export function decodeMobileShareRequest(input: unknown): MobileShareRequest {
+  const record = exactObject(input, ["title", "text", "url"], "share request");
+  const title = optionalShareField(record, "title");
+  const text = optionalShareField(record, "text");
+  const url = optionalShareField(record, "url");
+  if (!text && !url) {
+    throw new Error("share request must include text or url");
+  }
+  return { title, text, url };
+}
+
+export abstract class MobileShareCapability extends Service {
+  constructor(ctx: Context) {
+    super(ctx, "mobileShare");
+  }
+
+  abstract share(
+    request: MobileShareRequest,
+    signal: AbortSignal,
+  ): Promise<void>;
+}
+
+// Cordis context services exposed to mobile contribution plugins.
+declare module "cordis" {
+  interface Context {
+    mobileCommands: MobileCommandRegistry;
+    mobileNotifications: MobileNotificationCapability;
+    mobileClipboard: MobileClipboardCapability;
+    mobileShare: MobileShareCapability;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "DOM"],
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# @frockbot/mobile-core
-
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.