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

+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/**/*"]
}