Add extensions to the EvenHub API

This commit is contained in:
James Babcock committed 2026-08-17 01:57:14 -07:00
1 parent eab5a17b6d
commit 221dbb77ea
11 files changed
+844 -7

No files matched your search

+18 -4
View File
@@ -38,11 +38,12 @@ To install, run
## Features
* A voice assistant that wakes up when you say "Hey Even", transcribes text
with an on-device model, OpenAI Whisper, ElevenLabs, or Soniox API, and responds
to queries and commands using an Anthropic or OpenAI model (requires an API
key), or using your own long-running OpenClaw agent (see "Connecting an
external agent" below).
with an on-device model, OpenAI Whisper, ElevenLabs, or Soniox API, and
responds to queries and commands using an onboard model (Qwen3 4B, slow)
or with an Anthropic or OpenAI model (requires an API key), or using your
own long-running OpenClaw agent (see "Connecting an external agent" below).
* Multitasking, with an app-switcher sidebar and app launcher
* Mostly-compatible with EvenHub apps
* A lock screen; glasses lock automatically when you take them off and unlock
when you unlock your phone
* Full-screen apps can use the full 640x480 display area (rather than the
@@ -88,6 +89,19 @@ OpenClaw agent with the phone plugged into its host can perform the whole
setup itself. Note that a pulled settings file contains your API keys, so
treat it as a secret (the default output path is gitignored here).
## EvenHub App Notes
Faceclaw is mostly compatible with EvenHub apps. If you are developing an
app or using an open source app, you can package it into an EHPK file, send
it to your phone, and open it in the file browser to install. Or, you can log
into EvenHub and download apps there.
Faceclaw runs EvenHub apps through an emulation layer; you may run into bugs
and differences in behavior. If you run into bugs, please try tunning them in
the stock Android app before you report them to the app's creator. If you're
developing your own app and plan to submit it to the Hub, be sure to test it in
the stock Android app before submitting.
## Additional Caveats
Some permissions are used, but may not reliably prompted for. Go to Android
+113
View File
@@ -0,0 +1,113 @@
import { getDefaultSmallFont } from "../../graphics/bdffont";
import { GrayImage } from "../../graphics/image";
import { truncateText } from "../../graphics/textwrap";
import { Layer, type DashboardInputEvent, type LayerContext, type PaintBelow } from "../../ui/layers";
import { drawSelectionHighlight } from "../../ui/menu";
const DIALOG_X = 8;
const DIALOG_Y = 8;
const DIALOG_WIDTH = 272;
const PADDING = 10;
const HEADER_STEP = 16;
const SERVICE_STEP = 15;
const ACTION_ROW_HEIGHT = 20;
const SERVICE_LABELS: Record<string, string> = {
openai: "OpenAI",
anthropic: "Anthropic",
soniox: "Soniox",
elevenlabs: "ElevenLabs",
mapbox: "Mapbox",
};
export type ApiKeyRequestItem = { id: string; configured: boolean };
/**
* Consent dialog shown when an EvenHub app calls requestApiKeyAccess: lists the
* requested API-key services (marking any the user hasn't configured) and asks
* Allow / Deny. Allow shares the configured keys' values with the app; Deny (or
* double-click) shares nothing.
*/
export class EvenHubApiKeyDialogLayer implements Layer {
/** 0 = Allow, 1 = Deny. */
private selectedIndex = 0;
private resolved = false;
constructor(
private readonly appName: string,
private readonly services: ApiKeyRequestItem[],
private readonly onConfirm: () => void,
private readonly onCancel: () => void,
) {}
paint(ctx: LayerContext, paintBelow: PaintBelow): GrayImage {
const font = getDefaultSmallFont();
const { height: viewportHeight } = ctx.stack.getBaseSize();
const image = paintBelow();
const textWidth = DIALOG_WIDTH - 2 * PADDING - 4;
const left = DIALOG_X + PADDING + 2;
const bodyTop = PADDING + HEADER_STEP + 6 + this.services.length * SERVICE_STEP + 8;
const height = Math.min(bodyTop + 2 * ACTION_ROW_HEIGHT + PADDING, viewportHeight - 2 * DIALOG_Y);
image.fillRoundedRect(DIALOG_X, DIALOG_Y, DIALOG_WIDTH, height, 1);
image.drawRoundedRect(DIALOG_X, DIALOG_Y, DIALOG_WIDTH, height, 72);
let y = DIALOG_Y + PADDING;
image.drawText(font, left, y, truncateText(font, `${this.appName} wants your keys:`, textWidth), 235);
y += HEADER_STEP + 6;
for (const service of this.services) {
const label = SERVICE_LABELS[service.id] ?? service.id;
const text = service.configured ? label : `${label} (not set)`;
image.drawText(font, left + 8, y, truncateText(font, text, textWidth - 8), service.configured ? 220 : 130);
y += SERVICE_STEP;
}
y += 4;
const focused = ctx.stack.isFocused();
const actions = ["Allow", "Deny"];
for (let index = 0; index < actions.length; index++) {
const rowY = y + index * ACTION_ROW_HEIGHT;
const selected = index === this.selectedIndex;
if (selected) {
drawSelectionHighlight(image, DIALOG_X + 12, rowY, DIALOG_WIDTH - 24, ACTION_ROW_HEIGHT - 1, focused, 8);
}
image.drawText(font, DIALOG_X + 22, rowY + 3, actions[index]!, selected ? 255 : 200);
}
return image;
}
handleInput(event: DashboardInputEvent, ctx: LayerContext): void {
switch (event.type) {
case "scroll-up":
case "scroll-down":
this.selectedIndex = (this.selectedIndex + 1) % 2;
return;
case "click":
this.resolve(ctx, this.selectedIndex === 0);
return;
case "double-click":
this.resolve(ctx, false);
return;
default:
return;
}
}
onRemoved(): void {
// Dismissed some other way (window closed): treat as deny.
if (!this.resolved) {
this.resolved = true;
this.onCancel();
}
}
private resolve(ctx: LayerContext, allowed: boolean): void {
if (this.resolved) return;
this.resolved = true;
ctx.stack.pop();
if (allowed) this.onConfirm();
else this.onCancel();
}
}
+1
View File
@@ -68,6 +68,7 @@ export function createEvenHubWindow(
requestRender: created.requestRender,
closeWindow: () => shell.closeWindow(windowId),
focusSwitcher: () => shell.yieldFocusToSidebar(),
pushOverlay: (layer) => created.stack.push(layer),
});
// FOREGROUND_ENTER/EXIT for the app on shell focus changes.
+288 -1
View File
@@ -20,7 +20,21 @@
import { ApplicationSettings } from "@nativescript/core";
import { GrayImage } from "../../graphics/image";
import { EvenHubFont } from "../../graphics/evenhub-font";
import { type DashboardInputEvent } from "../../ui/layers";
import { type DashboardInputEvent, type Layer } from "../../ui/layers";
import {
anthropicApiKeySetting,
elevenLabsApiKeySetting,
mapboxApiKeySetting,
openAiApiKeySetting,
sonioxApiKeySetting,
} from "../../ui/dashboard-settings";
import {
buildSoundSequencePayload,
phraseDurationMs,
CFW_SEQ_MAX,
type Step,
} from "../../ui/sound-effects";
import { EvenHubApiKeyDialogLayer } from "./api-key-dialog";
import {
asRecord,
eventCaptureContainer,
@@ -44,6 +58,8 @@ import { ensureFineLocationPermission } from "../../g2/android-permissions";
const UPNG = require("upng-js");
declare const com: any;
/** OsEventTypeList values (PB ordinals). */
const CLICK_EVENT = 0;
const SCROLL_TOP_EVENT = 1;
@@ -157,6 +173,72 @@ export const EVENHUB_BRIDGE_INJECT_SCRIPT = `
})();
`;
/**
* Injected at document-start (after the stock bridge shim): defines
* `window.getFaceclawExtensions`, the single entry point for Faceclaw-only
* capabilities (see the faceclaw-extensions package). It never touches the
* standard SDK or any prototype — everything lives behind this one global, so
* apps stay compatible with the stock Even app (where the global is absent).
*
* RPC uses its own id-keyed promise map and `__fcExtResolve`, kept separate
* from the stock `__fcResolve` channel. Events arrive via `__fcExtEvent`.
* `<VERSION>` is interpolated by buildFaceclawExtensionsScript at load.
*/
export function buildFaceclawExtensionsScript(versionString: string): string {
return `
(function () {
if (window.getFaceclawExtensions) return;
var VERSION = ${JSON.stringify(versionString)};
var pending = {};
var nextId = 1;
window.__fcExtResolve = function (id, ok, value) {
var entry = pending[id];
if (!entry) return;
delete pending[id];
(ok ? entry[0] : entry[1])(value);
};
function call(method, params) {
return new Promise(function (resolve, reject) {
var id = nextId++;
pending[id] = [resolve, reject];
window.__faceclawEvenHub.postMessage("faceclawExt", JSON.stringify([method].concat(params || [])), id);
});
}
function send(method, params) {
// Fire-and-forget: id 0 tells the host no response is expected.
window.__faceclawEvenHub.postMessage("faceclawExt", JSON.stringify([method].concat(params || [])), 0);
}
var listeners = {};
window.__fcExtEvent = function (name, data) {
var arr = listeners[name];
if (!arr) return;
for (var i = 0; i < arr.slice().length; i++) {
try { arr[i](data); } catch (e) { if (window.console) console.error(e); }
}
};
function on(name, cb) {
(listeners[name] || (listeners[name] = [])).push(cb);
return function () {
var arr = listeners[name];
if (!arr) return;
var i = arr.indexOf(cb);
if (i >= 0) arr.splice(i, 1);
};
}
var extensions = {
getVersion: function () { return VERSION; },
returnToAppSwitcher: function () { send("returnToAppSwitcher"); },
quit: function () { send("quit"); },
addWindowLifecycleListener: function (cb) { return on("windowLifecycle", cb); },
getConfiguredApiKeys: function () { return call("getConfiguredApiKeys"); },
requestApiKeyAccess: function (services) { return call("requestApiKeyAccess", [services || []]); },
playBuzzer: function (steps) { return call("playBuzzer", [steps || []]); }
};
window.getFaceclawExtensions = function () { return extensions; };
})();
`;
}
/** Stock blocks a repeated createStartUpPageContainer ~2s before failing it. */
const DUPLICATE_CREATE_DELAY_MS = 2000;
@@ -172,6 +254,8 @@ export type EvenHubWindowHooks = {
closeWindow: () => void;
/** Hand focus to the app switcher (used to decline an app's quit request). */
focusSwitcher: () => void;
/** Push a modal overlay layer onto the app window (e.g. a consent prompt). */
pushOverlay: (layer: Layer) => void;
};
export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient {
@@ -195,6 +279,13 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient {
private imuRequested = false;
/** Non-null while the app has an active location subscription. */
private locationTracker: LocationTracker | null = null;
// Window-lifecycle tracking for the extension API (apps launch visible+focused).
private lastVisible = true;
private lastFocused = true;
/** Shell input focus on this window, sampled during paint. */
private shellFocused = true;
/** API-key services the user has granted this app this session. */
private readonly grantedApiKeys = new Set<string>();
private log: (message: string) => void;
constructor(manifest: EvenHubManifest, distDir: string, log: (message: string) => void) {
@@ -238,6 +329,9 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient {
}
paint(size: { width: number; height: number }, focused: boolean): GrayImage {
// Focus changes always trigger a repaint of the foreground window, so paint
// is a reliable place to sample shell input-focus for lifecycle events.
this.updateShellFocus(focused);
if (!this.pageCreated || !this.page) {
const image = new GrayImage(size.width, size.height, 0);
const font = EvenHubFont.get();
@@ -308,6 +402,10 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient {
// reads the accelerometer).
if (this.micRequested) evenHubMicRouter.notifyEligibilityChanged();
if (this.imuRequested) evenHubImuRouter.notifyEligibilityChanged();
// Focus is unknown until the next paint (a re-shown window repaints and
// re-asserts it; a hidden one won't, so treat it as unfocused meanwhile).
this.shellFocused = false;
this.recomputeLifecycle();
if (!this.pageCreated) return;
this.emitSysEvent(foreground ? FOREGROUND_ENTER_EVENT : FOREGROUND_EXIT_EVENT, 0);
}
@@ -317,6 +415,36 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient {
if (this.screenOn === on) return;
this.screenOn = on;
if (this.micRequested) evenHubMicRouter.notifyEligibilityChanged();
// As in setForeground: let the next paint re-assert focus.
this.shellFocused = false;
this.recomputeLifecycle();
}
// ----- extension window lifecycle -----
/** Sample shell input-focus (from paint) and emit focused/blurred on change. */
private updateShellFocus(focused: boolean): void {
if (this.shellFocused === focused) return;
this.shellFocused = focused;
this.recomputeLifecycle();
}
/**
* Emit visible/hidden and focused/blurred extension events on transition.
* visible = foreground && screen on; focused additionally needs shell input
* focus on this window.
*/
private recomputeLifecycle(): void {
const visible = this.foreground && this.screenOn;
const focused = visible && this.shellFocused;
if (visible !== this.lastVisible) {
this.lastVisible = visible;
this.pushExtEvent("windowLifecycle", { type: visible ? "visible" : "hidden" });
}
if (focused !== this.lastFocused) {
this.lastFocused = focused;
this.pushExtEvent("windowLifecycle", { type: focused ? "focused" : "blurred" });
}
}
// ----- microphone (EvenHubMicClient) -----
@@ -461,6 +589,10 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient {
* (kept lenient: a bare object works too).
*/
handleBridgeCall(handlerName: string, argsJson: string, callId: number): void {
if (handlerName === "faceclawExt") {
this.handleExtensionCall(argsJson, callId);
return;
}
void (async () => {
let result: unknown = null;
try {
@@ -638,6 +770,19 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient {
);
}
private resolveExtCall(callId: number, ok: boolean, value: unknown): void {
this.webViewHandle?.evaluateJs(
`window.__fcExtResolve && window.__fcExtResolve(${callId}, ${ok ? "true" : "false"}, ${JSON.stringify(value ?? null)})`,
);
}
/** Deliver an extension event to the app (e.g. windowLifecycle). */
private pushExtEvent(name: string, data: unknown): void {
this.webViewHandle?.evaluateJs(
`window.__fcExtEvent && window.__fcExtEvent(${JSON.stringify(name)}, ${JSON.stringify(data)})`,
);
}
private pushEvenHubEvent(payloadType: "sysEvent" | "textEvent" | "listEvent", jsonData: Record<string, unknown>): void {
this.pushMessage("evenHubEvent", { type: payloadType, jsonData: elideZeroFields(jsonData) });
}
@@ -656,6 +801,102 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient {
});
}
// ----- Faceclaw extensions (faceclawExt channel) -----
private handleExtensionCall(argsJson: string, callId: number): void {
void (async () => {
let ok = true;
let result: unknown = null;
try {
const args = JSON.parse(argsJson) as unknown[];
const method = String(args[0]);
result = await this.dispatchExtension(method, args.slice(1));
} catch (error) {
ok = false;
result = String(error);
this.log(`evenhub: extension call failed: ${error}`);
}
// id 0 is a fire-and-forget send; nothing is awaiting it.
if (callId !== 0) this.resolveExtCall(callId, ok, result);
})();
}
private async dispatchExtension(method: string, params: unknown[]): Promise<unknown> {
switch (method) {
case "returnToAppSwitcher":
this.windowHooks?.focusSwitcher();
return null;
case "quit":
// A real quit — bypasses the shutDown(1) → return-to-switcher behavior.
setTimeout(() => this.close(), 0);
return null;
case "getConfiguredApiKeys":
return configuredApiKeyServices();
case "requestApiKeyAccess":
return this.requestApiKeyAccess(Array.isArray(params[0]) ? params[0].map(String) : []);
case "playBuzzer":
await this.playBuzzer(Array.isArray(params[0]) ? params[0] : []);
return null;
default:
this.log(`evenhub: unknown extension method ${method}`);
return null;
}
}
/**
* Prompt the user (on the glasses) to share configured API keys with the app,
* resolving with the granted values. Services already granted this session
* skip the prompt; declining resolves with an empty map.
*/
private requestApiKeyAccess(services: string[]): Promise<Record<string, string>> {
const requested = services.filter(isKnownApiKeyService);
const buildGrant = (): Record<string, string> => {
const out: Record<string, string> = {};
for (const id of requested) {
if (!this.grantedApiKeys.has(id)) continue;
const value = apiKeyValue(id);
if (value) out[id] = value;
}
return out;
};
if (requested.length === 0 || requested.every((id) => this.grantedApiKeys.has(id))) {
return Promise.resolve(buildGrant());
}
if (!this.windowHooks) return Promise.resolve({});
return new Promise((resolve) => {
const dialog = new EvenHubApiKeyDialogLayer(
this.manifest.name,
requested.map((id) => ({ id, configured: apiKeyValue(id).length > 0 })),
() => {
for (const id of requested) this.grantedApiKeys.add(id);
resolve(buildGrant());
},
() => resolve({}),
);
this.windowHooks?.pushOverlay(dialog);
this.windowHooks?.requestRender();
});
}
/** Play a piezo tone sequence, chunking/pacing past the firmware's 48-step cap. */
private async playBuzzer(rawSteps: unknown[]): Promise<void> {
const steps = normalizeBuzzerSteps(rawSteps);
if (steps.length === 0) return;
const communicator = activeCommunicator();
if (!communicator) return;
for (let i = 0; i < steps.length; i += CFW_SEQ_MAX) {
const chunk = steps.slice(i, i + CFW_SEQ_MAX);
const payload = buildSoundSequencePayload(chunk);
try {
communicator.playBuzzerSequence(payload.buffer);
} catch (error) {
this.log(`evenhub: playBuzzer failed: ${error}`);
return;
}
if (i + CFW_SEQ_MAX < steps.length) await delay(phraseDurationMs(chunk));
}
}
// ----- teardown -----
/** Close everything: glasses window, WebView, session. Idempotent. */
@@ -741,6 +982,52 @@ function clampImuFreq(freq: number): number {
return Math.min(1000, Math.max(100, snapped));
}
function activeCommunicator(): any {
if (!global.isAndroid) return null;
try {
return com.faceclaw.app.FaceclawBleCommunicator.getActive();
} catch {
return null;
}
}
/** The API-key services the extension API can surface, and their settings. */
const API_KEY_SERVICES = [
{ id: "openai", setting: openAiApiKeySetting },
{ id: "anthropic", setting: anthropicApiKeySetting },
{ id: "soniox", setting: sonioxApiKeySetting },
{ id: "elevenlabs", setting: elevenLabsApiKeySetting },
{ id: "mapbox", setting: mapboxApiKeySetting },
] as const;
function isKnownApiKeyService(id: string): boolean {
return API_KEY_SERVICES.some((service) => service.id === id);
}
function apiKeyValue(id: string): string {
return API_KEY_SERVICES.find((service) => service.id === id)?.setting.get().trim() ?? "";
}
/** Service ids the user has actually configured (non-empty key), names only. */
function configuredApiKeyServices(): string[] {
return API_KEY_SERVICES.filter((service) => service.setting.get().trim()).map((service) => service.id);
}
/** Coerce an app-supplied buzzer step list into validated {freq, ms, duty?}. */
function normalizeBuzzerSteps(raw: unknown[]): Step[] {
const out: Step[] = [];
for (const item of raw) {
if (!item || typeof item !== "object") continue;
const record = item as Record<string, unknown>;
const freq = Number(record.freq);
const ms = Number(record.ms);
if (!Number.isFinite(freq) || !Number.isFinite(ms)) continue;
const duty = record.duty === undefined ? undefined : Number(record.duty);
out.push({ freq, ms, duty: duty !== undefined && Number.isFinite(duty) ? duty : undefined });
}
return out;
}
/**
* Decode an uncompressed Windows BMP ('BM', BI_RGB) to 8bpp grayscale. Handles
* 1/4/8-bit paletted and 24/32-bit BGR(A), top-down or bottom-up. Returns null
+6 -2
View File
@@ -12,7 +12,8 @@
* host app is backgrounded (see FaceclawEvenHubWebView / the host).
*/
import { Application, Utils } from "@nativescript/core";
import { EVENHUB_BRIDGE_INJECT_SCRIPT, type EvenHubSession } from "./session";
import { EVENHUB_BRIDGE_INJECT_SCRIPT, buildFaceclawExtensionsScript, type EvenHubSession } from "./session";
import { FACECLAW_VERSION } from "../../version";
declare const android: any;
declare const com: any;
@@ -56,8 +57,11 @@ export function createEvenHubWebView(session: EvenHubSession): EvenHubWebView {
});
const host = originHost(session);
// Stock bridge shim first, then the Faceclaw extensions global (both at
// document-start, before any app JS).
const injectScript = EVENHUB_BRIDGE_INJECT_SCRIPT + buildFaceclawExtensionsScript(`Faceclaw/${FACECLAW_VERSION}`);
webView.setWebViewClient(
new com.faceclaw.app.FaceclawEvenHubWebViewClient(session.distDir, host, EVENHUB_BRIDGE_INJECT_SCRIPT, listener),
new com.faceclaw.app.FaceclawEvenHubWebViewClient(session.distDir, host, injectScript, listener),
);
webView.addJavascriptInterface(new com.faceclaw.app.FaceclawEvenHubJsBridge(listener), "__faceclawEvenHub");
+88
View File
@@ -0,0 +1,88 @@
# faceclaw-extensions
Type definitions and a tiny helper for EvenHub apps that want to detect and use
**Faceclaw**-specific extension APIs.
[Faceclaw](https://github.com/jimrandomh/faceclaw) is an alternative host for
EvenHub apps: it runs them directly on the Even Realities G2 glasses instead of
through the stock Even Realities phone app. An app built against the standard
[`@evenrealities/even_hub_sdk`](https://www.npmjs.com/package/@evenrealities/even_hub_sdk)
runs unchanged. This package lets it *optionally* light up a few extra
capabilities when it detects it's running inside Faceclaw.
## Design
There is exactly one entry point: the injected global
`window.getFaceclawExtensions`.
- Inside Faceclaw it is `(() => FaceclawExtensions) | null`.
- In the stock Even app (and browsers, and any other host) it is `undefined`.
Nothing on the standard SDK, on `window`, or on any built-in prototype is
modified — every Faceclaw capability lives behind this single global. That keeps
it obvious what is an extension, and means an app that uses these APIs still runs
correctly everywhere else (it just skips the extras). New capabilities are only
ever *added*, never changed, so pinning a version stays backwards-compatible.
## Install
```sh
npm install faceclaw-extensions
```
(Type-only today; no runtime dependencies.)
## Usage
```ts
import { getFaceclawExtensions } from "faceclaw-extensions";
const fc = getFaceclawExtensions();
if (!fc) {
// Not running in Faceclaw — use only the standard EvenHub SDK.
} else {
console.log("host:", fc.getVersion()); // e.g. "Faceclaw/0.4.0"
// Pause work while the app isn't on-screen.
const off = fc.addWindowLifecycleListener((e) => {
if (e.type === "hidden" || e.type === "blurred") pause();
if (e.type === "visible" || e.type === "focused") resume();
});
// Ask for the user's OpenAI key (opens a consent prompt on the glasses).
const configured = await fc.getConfiguredApiKeys();
if (configured.includes("openai")) {
const granted = await fc.requestApiKeyAccess(["openai"]);
if (granted.openai) startCloudFeature(granted.openai);
}
// Beep.
await fc.playBuzzer([
{ freq: 880, ms: 90 },
{ freq: 0, duty: 0, ms: 40 }, // a rest
{ freq: 1320, ms: 160 },
]);
}
```
## API
See `src/index.ts` for the full, documented `FaceclawExtensions` interface. In
brief:
| Method | Description |
| --- | --- |
| `getVersion(): string` | Host version, e.g. `"Faceclaw/0.4.0"`. |
| `returnToAppSwitcher(): void` | Yield focus to the app switcher; keep running. |
| `quit(): void` | Close the app for real (not overridable). |
| `addWindowLifecycleListener(fn): () => void` | `visible`/`hidden` and `focused`/`blurred` events. |
| `getConfiguredApiKeys(): Promise<ApiKeyService[]>` | Which keys the user configured (names only). |
| `requestApiKeyAccess(services): Promise<Partial<Record<ApiKeyService, string>>>` | Prompt for and return key values. |
| `playBuzzer(steps): Promise<void>` | Play a piezo tone sequence. |
`ApiKeyService` is one of `"openai" | "anthropic" | "soniox" | "elevenlabs" | "mapbox"`.
## Stability
Pre-1.0: the surface may still change. Once it stabilizes, additive-only changes
are the rule.
+120
View File
@@ -0,0 +1,120 @@
/**
* faceclaw-extensions — type definitions for the Faceclaw extension API.
*
* Faceclaw (https://github.com/…/faceclaw) is an alternative host for EvenHub
* apps that runs them directly on the Even Realities G2 glasses instead of the
* stock Even app. An app built against the standard `@evenrealities/even_hub_sdk`
* runs unchanged. When it happens to be running inside Faceclaw, this package
* lets it detect that and reach a few extra, Faceclaw-only capabilities.
*
* Design contract:
* - The only entry point is the injected global `window.getFaceclawExtensions`.
* It is `(() => FaceclawExtensions) | null` inside Faceclaw and `undefined`
* in the stock Even app (and any other host). Nothing on the standard SDK or
* on built-in prototypes is modified — every Faceclaw capability lives behind
* this one global, so it is always obvious what is an extension and standard
* apps keep working everywhere.
* - New functionality is only ever *added* here; existing members keep their
* behavior, so pinning a version stays backwards-compatible.
*
* Usage:
* ```ts
* import { getFaceclawExtensions } from "faceclaw-extensions";
*
* const fc = getFaceclawExtensions();
* if (fc) {
* console.log("Running in", fc.getVersion()); // "Faceclaw/0.4.0"
* fc.addWindowLifecycleListener((e) => {
* if (e.type === "hidden") pauseExpensiveWork();
* });
* }
* ```
*/
/** Third-party API-key services whose keys the user may have configured in Faceclaw. */
export type ApiKeyService = "openai" | "anthropic" | "soniox" | "elevenlabs" | "mapbox";
/**
* One step of a piezo-buzzer tone sequence. The G2 has a single monophonic PWM
* buzzer; a sequence plays back-to-back steps on the firmware's own timer.
*/
export interface BuzzerStep {
/** Tone frequency in Hz. The piezo is loudest ~1–4 kHz; faint below ~150 Hz. */
freq: number;
/** Step duration in milliseconds (1–65535). */
ms: number;
/** PWM duty cycle, 0–100 (default 50). `duty: 0` is a rest (silence) for `ms`. */
duty?: number;
}
/**
* Window lifecycle transitions, delivered to
* {@link FaceclawExtensions.addWindowLifecycleListener}:
* - `visible` / `hidden`: the app's glasses window became the shown surface, or
* stopped being it — because the user switched the foreground window or the
* phone screen turned on/off. A hidden app keeps running (Faceclaw keeps its
* webview alive) but nothing it renders reaches the glasses.
* - `focused` / `blurred`: input focus moved onto or off the app's window (e.g.
* the user opened the app switcher). A blurred-but-visible app is still shown
* but no longer receives taps/scrolls.
*
* An app can assume it starts `visible` and `focused` at launch; events report
* changes from there.
*/
export type WindowLifecycleEventType = "visible" | "hidden" | "focused" | "blurred";
export interface WindowLifecycleEvent {
type: WindowLifecycleEventType;
}
/**
* The Faceclaw-only capability surface. Obtained via {@link getFaceclawExtensions}.
* Every method is additive to the standard EvenHub SDK.
*/
export interface FaceclawExtensions {
/** Host version string, e.g. `"Faceclaw/0.4.0"`. */
getVersion(): string;
/**
* Hand input focus back to Faceclaw's app switcher without closing the app
* (it keeps running in the background). Equivalent to the user double-tapping
* out, but explicit.
*/
returnToAppSwitcher(): void;
/**
* Close this app for real and tear down its window. Unlike the stock
* `shutDownPageContainer(1)` — which Faceclaw interprets as "return to the app
* switcher" so double-tap-to-quit apps stay alive — this always quits.
*/
quit(): void;
/**
* Subscribe to window lifecycle changes (see {@link WindowLifecycleEvent}).
* Returns an unsubscribe function.
*/
addWindowLifecycleListener(listener: (event: WindowLifecycleEvent) => void): () => void;
/**
* List which API-key services the user has configured in Faceclaw. Returns
* only the service names, never the key values — use
* {@link requestApiKeyAccess} to obtain values (with the user's consent).
*/
getConfiguredApiKeys(): Promise<ApiKeyService[]>;
/**
* Ask the user to share one or more configured API keys with this app. Opens
* a consent prompt on the glasses. Resolves with a map of the granted keys'
* values (only for services that are both requested and configured); services
* the user declines, or that aren't configured, are absent. Resolves with an
* empty object if the user denies.
*/
requestApiKeyAccess(services: ApiKeyService[]): Promise<Partial<Record<ApiKeyService, string>>>;
/**
* Play a tone sequence on the glasses' piezo buzzer. Sequences longer than the
* firmware's per-message cap (48 steps) are split and paced automatically.
* Resolves once every message has been queued.
*/
playBuzzer(steps: BuzzerStep[]): Promise<void>;
}
declare global {
interface Window {
/** Injected by Faceclaw; `undefined` in the stock Even app and other hosts. */
getFaceclawExtensions?: (() => FaceclawExtensions) | null;
}
}
/**
* Return the Faceclaw extension API if the app is running inside Faceclaw, or
* `null` otherwise (the stock Even app, a browser, etc.). Safe to call anywhere.
*/
export declare function getFaceclawExtensions(): FaceclawExtensions | null;
+40
View File
@@ -0,0 +1,40 @@
/**
* faceclaw-extensions — type definitions for the Faceclaw extension API.
*
* Faceclaw (https://github.com/…/faceclaw) is an alternative host for EvenHub
* apps that runs them directly on the Even Realities G2 glasses instead of the
* stock Even app. An app built against the standard `@evenrealities/even_hub_sdk`
* runs unchanged. When it happens to be running inside Faceclaw, this package
* lets it detect that and reach a few extra, Faceclaw-only capabilities.
*
* Design contract:
* - The only entry point is the injected global `window.getFaceclawExtensions`.
* It is `(() => FaceclawExtensions) | null` inside Faceclaw and `undefined`
* in the stock Even app (and any other host). Nothing on the standard SDK or
* on built-in prototypes is modified — every Faceclaw capability lives behind
* this one global, so it is always obvious what is an extension and standard
* apps keep working everywhere.
* - New functionality is only ever *added* here; existing members keep their
* behavior, so pinning a version stays backwards-compatible.
*
* Usage:
* ```ts
* import { getFaceclawExtensions } from "faceclaw-extensions";
*
* const fc = getFaceclawExtensions();
* if (fc) {
* console.log("Running in", fc.getVersion()); // "Faceclaw/0.4.0"
* fc.addWindowLifecycleListener((e) => {
* if (e.type === "hidden") pauseExpensiveWork();
* });
* }
* ```
*/
/**
* Return the Faceclaw extension API if the app is running inside Faceclaw, or
* `null` otherwise (the stock Even app, a browser, etc.). Safe to call anywhere.
*/
export function getFaceclawExtensions() {
const getter = typeof window !== "undefined" ? window.getFaceclawExtensions : null;
return typeof getter === "function" ? getter() : null;
}
+21
View File
@@ -0,0 +1,21 @@
{
"name": "faceclaw-extensions",
"version": "0.1.0",
"description": "Type definitions and helpers for EvenHub apps to detect and use Faceclaw-specific extension APIs.",
"license": "MIT",
"type": "module",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js"
}
},
"files": ["dist", "README.md"],
"scripts": {
"build": "tsc -p tsconfig.json"
},
"keywords": ["evenhub", "even-realities", "g2", "faceclaw", "smart-glasses"],
"sideEffects": false
}
+136
View File
@@ -0,0 +1,136 @@
/**
* faceclaw-extensions — type definitions for the Faceclaw extension API.
*
* Faceclaw (https://github.com/…/faceclaw) is an alternative host for EvenHub
* apps that runs them directly on the Even Realities G2 glasses instead of the
* stock Even app. An app built against the standard `@evenrealities/even_hub_sdk`
* runs unchanged. When it happens to be running inside Faceclaw, this package
* lets it detect that and reach a few extra, Faceclaw-only capabilities.
*
* Design contract:
* - The only entry point is the injected global `window.getFaceclawExtensions`.
* It is `(() => FaceclawExtensions) | null` inside Faceclaw and `undefined`
* in the stock Even app (and any other host). Nothing on the standard SDK or
* on built-in prototypes is modified — every Faceclaw capability lives behind
* this one global, so it is always obvious what is an extension and standard
* apps keep working everywhere.
* - New functionality is only ever *added* here; existing members keep their
* behavior, so pinning a version stays backwards-compatible.
*
* Usage:
* ```ts
* import { getFaceclawExtensions } from "faceclaw-extensions";
*
* const fc = getFaceclawExtensions();
* if (fc) {
* console.log("Running in", fc.getVersion()); // "Faceclaw/0.4.0"
* fc.addWindowLifecycleListener((e) => {
* if (e.type === "hidden") pauseExpensiveWork();
* });
* }
* ```
*/
/** Third-party API-key services whose keys the user may have configured in Faceclaw. */
export type ApiKeyService = "openai" | "anthropic" | "soniox" | "elevenlabs" | "mapbox";
/**
* One step of a piezo-buzzer tone sequence. The G2 has a single monophonic PWM
* buzzer; a sequence plays back-to-back steps on the firmware's own timer.
*/
export interface BuzzerStep {
/** Tone frequency in Hz. The piezo is loudest ~1–4 kHz; faint below ~150 Hz. */
freq: number;
/** Step duration in milliseconds (1–65535). */
ms: number;
/** PWM duty cycle, 0–100 (default 50). `duty: 0` is a rest (silence) for `ms`. */
duty?: number;
}
/**
* Window lifecycle transitions, delivered to
* {@link FaceclawExtensions.addWindowLifecycleListener}:
* - `visible` / `hidden`: the app's glasses window became the shown surface, or
* stopped being it — because the user switched the foreground window or the
* phone screen turned on/off. A hidden app keeps running (Faceclaw keeps its
* webview alive) but nothing it renders reaches the glasses.
* - `focused` / `blurred`: input focus moved onto or off the app's window (e.g.
* the user opened the app switcher). A blurred-but-visible app is still shown
* but no longer receives taps/scrolls.
*
* An app can assume it starts `visible` and `focused` at launch; events report
* changes from there.
*/
export type WindowLifecycleEventType = "visible" | "hidden" | "focused" | "blurred";
export interface WindowLifecycleEvent {
type: WindowLifecycleEventType;
}
/**
* The Faceclaw-only capability surface. Obtained via {@link getFaceclawExtensions}.
* Every method is additive to the standard EvenHub SDK.
*/
export interface FaceclawExtensions {
/** Host version string, e.g. `"Faceclaw/0.4.0"`. */
getVersion(): string;
/**
* Hand input focus back to Faceclaw's app switcher without closing the app
* (it keeps running in the background). Equivalent to the user double-tapping
* out, but explicit.
*/
returnToAppSwitcher(): void;
/**
* Close this app for real and tear down its window. Unlike the stock
* `shutDownPageContainer(1)` — which Faceclaw interprets as "return to the app
* switcher" so double-tap-to-quit apps stay alive — this always quits.
*/
quit(): void;
/**
* Subscribe to window lifecycle changes (see {@link WindowLifecycleEvent}).
* Returns an unsubscribe function.
*/
addWindowLifecycleListener(listener: (event: WindowLifecycleEvent) => void): () => void;
/**
* List which API-key services the user has configured in Faceclaw. Returns
* only the service names, never the key values — use
* {@link requestApiKeyAccess} to obtain values (with the user's consent).
*/
getConfiguredApiKeys(): Promise<ApiKeyService[]>;
/**
* Ask the user to share one or more configured API keys with this app. Opens
* a consent prompt on the glasses. Resolves with a map of the granted keys'
* values (only for services that are both requested and configured); services
* the user declines, or that aren't configured, are absent. Resolves with an
* empty object if the user denies.
*/
requestApiKeyAccess(services: ApiKeyService[]): Promise<Partial<Record<ApiKeyService, string>>>;
/**
* Play a tone sequence on the glasses' piezo buzzer. Sequences longer than the
* firmware's per-message cap (48 steps) are split and paced automatically.
* Resolves once every message has been queued.
*/
playBuzzer(steps: BuzzerStep[]): Promise<void>;
}
declare global {
interface Window {
/** Injected by Faceclaw; `undefined` in the stock Even app and other hosts. */
getFaceclawExtensions?: (() => FaceclawExtensions) | null;
}
}
/**
* Return the Faceclaw extension API if the app is running inside Faceclaw, or
* `null` otherwise (the stock Even app, a browser, etc.). Safe to call anywhere.
*/
export function getFaceclawExtensions(): FaceclawExtensions | null {
const getter = typeof window !== "undefined" ? window.getFaceclawExtensions : null;
return typeof getter === "function" ? getter() : null;
}
+13
View File
@@ -0,0 +1,13 @@
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "bundler",
"declaration": true,
"outDir": "dist",
"strict": true,
"skipLibCheck": true,
"lib": ["ESNext", "DOM"]
},
"include": ["src/**/*"]
}