forked from Blendman974/faceclaw
Add extensions to the EvenHub API
This commit is contained in:
1 parent
eab5a17b6d
commit
221dbb77ea
11 files changed
+844
-7
No files matched your search
@@ -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.
|
||||
Vendored
+120
@@ -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;
|
||||
Vendored
+40
@@ -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;
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2020",
|
||||
"module": "ESNext",
|
||||
"moduleResolution": "bundler",
|
||||
"declaration": true,
|
||||
"outDir": "dist",
|
||||
"strict": true,
|
||||
"skipLibCheck": true,
|
||||
"lib": ["ESNext", "DOM"]
|
||||
},
|
||||
"include": ["src/**/*"]
|
||||
}
|
||||
Reference in new issue
Block a user