forked from Blendman974/faceclaw
Fixes to evenhub extensions library
This commit is contained in:
1 parent
4bf2769d24
commit
07859c95ad
8 files changed
+203
-34
No files matched your search
@@ -51,8 +51,9 @@ if (!fc) {
|
||||
}
|
||||
```
|
||||
|
||||
`getFaceclawExtensions()` returns `null` everywhere except inside Faceclaw:
|
||||
in the stock Even app, in the EvenHub simulator, in a browser, and in Node.
|
||||
`getFaceclawExtensions()` returns `null` everywhere except inside Faceclaw
|
||||
0.8.3 or later: in the stock Even app, in the EvenHub simulator, in a browser,
|
||||
and in Node.
|
||||
Faceclaw installs the API before any page script runs, so you can call it at
|
||||
startup. You don't need to wait for the bridge first.
|
||||
|
||||
@@ -81,7 +82,12 @@ if (fc && fc.apiVersion >= 2) {
|
||||
}
|
||||
```
|
||||
|
||||
Everything in this release is API level 1.
|
||||
Everything in this release is API level 1, which Faceclaw 0.8.3 and later
|
||||
implement. Faceclaw 0.8.0–0.8.2 injected an incomplete, unversioned preview of
|
||||
the API; `getFaceclawExtensions()` returns `null` there, so whenever it returns
|
||||
the API, every level-1 member is present. If you use
|
||||
`window.getFaceclawExtensions` directly, check that `apiVersion` is a number
|
||||
before relying on it.
|
||||
|
||||
## TypeScript
|
||||
|
||||
@@ -284,9 +290,16 @@ fc.setAssistantTools([
|
||||
|
||||
The assistant sees each tool under your package name, as
|
||||
`app.<packageName>.set_bpm`. Whatever the handler returns is reported back to
|
||||
the assistant. If it throws, the assistant gets the error message. Tools are
|
||||
removed when the app closes; call `setAssistantTools([])` to remove them
|
||||
sooner.
|
||||
the assistant. If it throws, the assistant gets the error message. A handler
|
||||
has 10 seconds to finish before the assistant is told the tool timed out.
|
||||
Tools are removed when the app closes; call `setAssistantTools([])` to remove
|
||||
them sooner.
|
||||
|
||||
Tool names are 1–64 letters, digits, underscores or hyphens. `parameters`
|
||||
must be an object schema (`type: "object"`) without a top-level `oneOf`,
|
||||
`anyOf` or `allOf`, since that is what the assistant's model providers accept.
|
||||
Faceclaw skips a tool that breaks these rules and logs a warning to the app's
|
||||
console.
|
||||
|
||||
### API keys
|
||||
|
||||
|
||||
@@ -42,7 +42,7 @@ carry them out.
|
||||
|
||||
| Property | Modifier | Type | Description |
|
||||
| ------ | ------ | ------ | ------ |
|
||||
| <a id="property-apiversion"></a> `apiVersion` | `readonly` | `number` | The extension API level the host implements. It is `1` for the API described here, and increases by one each time members are added. Members added later are documented with the level that introduced them, so an app can check for them before calling: `if (fc.apiVersion >= 2) fc.someNewerMethod();` |
|
||||
| <a id="property-apiversion"></a> `apiVersion` | `readonly` | `number` | The extension API level the host implements. It is `1` for the API described here (Faceclaw 0.8.3 and later), and increases by one each time members are added. Members added later are documented with the level that introduced them, so an app can check for them before calling: `if (fc.apiVersion >= 2) fc.someNewerMethod();` |
|
||||
|
||||
#### Methods
|
||||
|
||||
@@ -165,7 +165,9 @@ firmware's per-message limit of 48 steps are split and paced automatically.
|
||||
`Promise`\<`void`\>
|
||||
|
||||
A promise that resolves once every part of the sequence has been
|
||||
queued on the glasses, which can be before it finishes playing.
|
||||
queued on the glasses, which can be before it finishes playing. It
|
||||
rejects if sending to the glasses fails. If the glasses aren't
|
||||
connected, the sequence is dropped and the promise still resolves.
|
||||
|
||||
##### addCompassListener()
|
||||
|
||||
@@ -251,6 +253,9 @@ setAssistantTools(tools): void;
|
||||
Declare the app's voice-assistant tools, replacing any set earlier. Each
|
||||
tool's `handler` runs in the app when the assistant calls it.
|
||||
|
||||
Faceclaw skips a tool whose `name` or `parameters` break the rules in
|
||||
[AssistantTool](#assistanttool), and logs a warning to the app's console saying why.
|
||||
|
||||
###### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
@@ -436,6 +441,10 @@ Return the Faceclaw extension API if the app is running inside Faceclaw, or
|
||||
Safe to call anywhere, at any time; Faceclaw installs the API before any page
|
||||
script runs.
|
||||
|
||||
It also returns `null` in Faceclaw 0.8.0–0.8.2, which had an incomplete,
|
||||
unversioned preview of the API. Whenever it returns the API, every member
|
||||
of API level 1 is present.
|
||||
|
||||
#### Returns
|
||||
|
||||
[`FaceclawExtensions`](#faceclawextensions) \| `null`
|
||||
@@ -878,8 +887,8 @@ The assistant sees the tool namespaced by the app's package name, as
|
||||
|
||||
| Property | Type | Default value | Description |
|
||||
| ------ | ------ | ------ | ------ |
|
||||
| <a id="property-name"></a> `name` | `string` | `undefined` | Bare tool name (no package prefix), for example `"set_color"`. |
|
||||
| <a id="property-name"></a> `name` | `string` | `undefined` | Bare tool name (no package prefix), for example `"set_color"`: 1–64 letters, digits, underscores or hyphens. |
|
||||
| <a id="property-description"></a> `description` | `string` | `undefined` | What the tool does. The assistant reads this to decide when to call it. |
|
||||
| <a id="property-parameters"></a> `parameters?` | [`JsonSchema`](#jsonschema) | `{ type: "object", properties: {} }` | JSON Schema for the arguments object the assistant will pass to `handler`. |
|
||||
| <a id="property-parameters"></a> `parameters?` | [`JsonSchema`](#jsonschema) | `{ type: "object", properties: {} }` | JSON Schema for the arguments object the assistant will pass to `handler`. It must describe an object (`type: "object"`), with any `properties` an object and any `required` an array of names, and must not use `oneOf`, `anyOf` or `allOf` at the top level. These are the schemas the assistant's model providers accept. |
|
||||
| <a id="property-availability"></a> `availability?` | `"open"` \| `"foreground"` | `"foreground"` | When the tool can be called: `"foreground"` only while the app owns the visible window, or `"open"` any time the app is running, including in the background. |
|
||||
| <a id="property-handler"></a> `handler` | (`args`) => `unknown` | `undefined` | Called when the assistant invokes the tool. Return a string, or any JSON-serializable value, to report back to the assistant. Throw (or reject) to report an error. May be async. |
|
||||
| <a id="property-handler"></a> `handler` | (`args`) => `unknown` | `undefined` | Called when the assistant invokes the tool. Return a string, or any JSON-serializable value, to report back to the assistant. Throw (or reject) to report an error. May be async, but must finish within 10 seconds, or the assistant is told the tool timed out. |
|
||||
@@ -489,12 +489,19 @@ export type JsonSchema = Record<string, unknown>;
|
||||
* @group Assistant tools
|
||||
*/
|
||||
export interface AssistantTool<Args = any> {
|
||||
/** Bare tool name (no package prefix), for example `"set_color"`. */
|
||||
/**
|
||||
* Bare tool name (no package prefix), for example `"set_color"`: 1–64
|
||||
* letters, digits, underscores or hyphens.
|
||||
*/
|
||||
name: string;
|
||||
/** What the tool does. The assistant reads this to decide when to call it. */
|
||||
description: string;
|
||||
/**
|
||||
* JSON Schema for the arguments object the assistant will pass to `handler`.
|
||||
* It must describe an object (`type: "object"`), with any `properties` an
|
||||
* object and any `required` an array of names, and must not use `oneOf`,
|
||||
* `anyOf` or `allOf` at the top level. These are the schemas the
|
||||
* assistant's model providers accept.
|
||||
* @defaultValue { type: "object", properties: {} }
|
||||
*/
|
||||
parameters?: JsonSchema;
|
||||
@@ -508,7 +515,8 @@ export interface AssistantTool<Args = any> {
|
||||
/**
|
||||
* Called when the assistant invokes the tool. Return a string, or any
|
||||
* JSON-serializable value, to report back to the assistant. Throw (or reject)
|
||||
* to report an error. May be async.
|
||||
* to report an error. May be async, but must finish within 10 seconds, or
|
||||
* the assistant is told the tool timed out.
|
||||
*/
|
||||
handler: (args: Args) => unknown;
|
||||
}
|
||||
@@ -525,9 +533,9 @@ export interface AssistantTool<Args = any> {
|
||||
export interface FaceclawExtensions {
|
||||
/**
|
||||
* The extension API level the host implements. It is `1` for the API
|
||||
* described here, and increases by one each time members are added. Members
|
||||
* added later are documented with the level that introduced them, so an app
|
||||
* can check for them before calling:
|
||||
* described here (Faceclaw 0.8.3 and later), and increases by one each time
|
||||
* members are added. Members added later are documented with the level that
|
||||
* introduced them, so an app can check for them before calling:
|
||||
*
|
||||
* ```ts
|
||||
* if (fc.apiVersion >= 2) fc.someNewerMethod();
|
||||
@@ -587,7 +595,9 @@ export interface FaceclawExtensions {
|
||||
* firmware's per-message limit of 48 steps are split and paced automatically.
|
||||
*
|
||||
* @returns A promise that resolves once every part of the sequence has been
|
||||
* queued on the glasses, which can be before it finishes playing.
|
||||
* queued on the glasses, which can be before it finishes playing. It
|
||||
* rejects if sending to the glasses fails. If the glasses aren't
|
||||
* connected, the sequence is dropped and the promise still resolves.
|
||||
*/
|
||||
playBuzzer(steps: BuzzerStep[]): Promise<void>;
|
||||
|
||||
@@ -632,6 +642,9 @@ export interface FaceclawExtensions {
|
||||
* Declare the app's voice-assistant tools, replacing any set earlier. Each
|
||||
* tool's `handler` runs in the app when the assistant calls it.
|
||||
*
|
||||
* Faceclaw skips a tool whose `name` or `parameters` break the rules in
|
||||
* {@link AssistantTool}, and logs a warning to the app's console saying why.
|
||||
*
|
||||
* @param tools - The tools to offer. Pass `[]` to remove them all.
|
||||
*/
|
||||
setAssistantTools(tools: AssistantTool[]): void;
|
||||
@@ -718,7 +731,9 @@ declare global {
|
||||
/**
|
||||
* Injected by Faceclaw before any page script runs. `undefined` in the
|
||||
* stock Even app and other hosts. Prefer {@link getFaceclawExtensions},
|
||||
* which checks for it.
|
||||
* which checks for it. If you call it directly, check that the result's
|
||||
* `apiVersion` is a number: Faceclaw 0.8.0–0.8.2 returned an incomplete
|
||||
* preview without one.
|
||||
*/
|
||||
getFaceclawExtensions?: (() => FaceclawExtensions) | null;
|
||||
}
|
||||
@@ -730,9 +745,17 @@ declare global {
|
||||
* Safe to call anywhere, at any time; Faceclaw installs the API before any page
|
||||
* script runs.
|
||||
*
|
||||
* It also returns `null` in Faceclaw 0.8.0–0.8.2, which had an incomplete,
|
||||
* unversioned preview of the API. Whenever it returns the API, every member
|
||||
* of API level 1 is present.
|
||||
*
|
||||
* @group Entry point
|
||||
*/
|
||||
export function getFaceclawExtensions(): FaceclawExtensions | null {
|
||||
const getter = typeof window !== "undefined" ? window.getFaceclawExtensions : null;
|
||||
return typeof getter === "function" ? getter() : null;
|
||||
if (typeof getter !== "function") return null;
|
||||
const extensions = getter();
|
||||
// Faceclaw 0.8.0–0.8.2 injected an unversioned preview with only some of
|
||||
// the level-1 members; treat it as absent.
|
||||
return extensions && typeof extensions.apiVersion === "number" ? extensions : null;
|
||||
}
|
||||
Reference in new issue
Block a user