@hosty-sdk/app 0.16.2 → 0.17.0

package/README.md

@@ -14,6 +14,8 @@ npm install @hosty-sdk/app
 | `@hosty-sdk/app/server` | server only | Core revalidation with caching, cookie helpers, the app-code route factory, the app secrets client |
 | `@hosty-sdk/app/react` | client | `<AppIdentityBridge />` — probe, silent recovery, fallback cards |
 | `@hosty-sdk/app/embedder` | client | verified responders — launch-code recovery and delegated tokens — plus the theme sender half, for anything that embeds Hosty apps |
+| `@hosty-sdk/app/providers` | anywhere | permission state, provider descriptors, speech contract types |
+| `@hosty-sdk/app/providers/server` | server only | `ProviderClient`: discovery, speech recognition, assistant handoffs and live credential validation |
 | `@hosty-sdk/app/theme` | anywhere | the shell→app theme protocol: constants, `resolveTheme`, `applyTheme`, `parseShellThemeMessage`, `themeBootstrapScript` / `createThemeBootstrapScript` |
 
 Minimal Next.js wiring:
@@ -205,3 +207,17 @@ capability and raw upload API. See [the complete contract](../../docs/features/h
 
 Assistant control requests use a 60-second deadline. Uploads accept an optional caller-owned
 `AbortSignal` and have no SDK-imposed deadline, so slow valid transfers are not aborted after a minute.
+
+## Speech And Assistant Providers
+
+Core 0.115.0 supports required `corePermissions` and optional `optionalCorePermissions` with
+`providers.speech-to-text` / `providers.assistant`. Each accepted permission covers all confirmed
+providers of that category. Read `new ProviderClient().permissions()` before offering optional UI.
+Select an app ID and interface key explicitly, use `list("speech-to-text")`, `speechCapabilities(...)`
+and `transcribe(selected, wavBlob, { signal })` on the server. Never expose the app service token to
+a browser. Transcription accepts the provider's documented format; the v1 baseline is 16 kHz mono
+PCM16 WAV. Browser microphone consent is separate from Core permission.
+
+`assistant(selected, getUserToken)` returns the existing `AssistantClient` with bounded provider
+credentials and the acting user's access. It does not expose general agent execution.
+See [Provider consumption](../../docs/features/provider-consumption/feature.md) for the full contract.

package/dist/assistant.js

@@ -51,7 +51,7 @@ export class AssistantClient {
             headers.set("authorization", `Bearer ${grant.token}`);
             if (typeof init.body === "string")
                 headers.set("content-type", "application/json");
-            const response = await fetch(`${this.baseUrl.replace(/\/$/, "")}${route}`, { ...init, headers, signal: init.signal ?? (controlDeadline ? AbortSignal.timeout(60_000) : undefined) });
+            const response = await fetch(`${this.baseUrl.replace(/\/$/, "")}${route}`, { ...init, redirect: "error", headers, signal: init.signal ?? (controlDeadline ? AbortSignal.timeout(60_000) : undefined) });
             if (response.status === 401 && attempt === 0)
                 continue;
             const body = await response.json().catch(() => null);

package/dist/install.d.ts

@@ -26,6 +26,7 @@ export interface InstallPlan {
     defaultAutostart?: boolean;
     system?: boolean;
     corePermissions?: string[];
+    optionalCorePermissions?: string[];
     requestedRoles?: string[];
     permissionDescriptions?: Record<string, string>;
     roleDescriptions?: Record<string, string>;
@@ -44,11 +45,20 @@ export interface InstallationSource {
     selectedRuntime?: string;
     updateAppId?: string;
     planDigest?: string;
+    /** Review optional grants for this installed app, without reinstalling it. */
+    permissionsAppId?: string;
 }
 export interface InstallationRequest {
     id: string;
     status: "draft" | "pending" | "executing" | "succeeded" | "denied" | "failed";
     plan: InstallPlan | null;
+    permissionPlan?: {
+        appId: string;
+        displayName: string;
+        required: string[];
+        optional: string[];
+        granted: string[];
+    } | null;
     approvalUrl: string;
     expiresAt: string;
     error?: string | null;

package/dist/providers-server.d.ts

@@ -0,0 +1,30 @@
+import { AssistantClient } from "./assistant.js";
+import { type AppPermissionState, type ProviderDescriptor, type ProviderInvocation, type ProviderKind, type SpeechCapabilities, type SpeechResult } from "./providers.js";
+export type ProviderServerOptions = {
+    appId?: string;
+    coreOrigin?: string;
+    serviceToken?: string;
+    /** The consumer's deployment topology; endpoints on Core loopback must be reached through its host. */
+    runningInContainer?: boolean;
+};
+/** Server-only provider client. Its app service token must never be sent to a browser or provider. */
+export declare class ProviderClient {
+    private readonly appId;
+    private readonly core;
+    private readonly service;
+    private readonly container;
+    constructor(options?: ProviderServerOptions);
+    private coreRequest;
+    permissions(signal?: AbortSignal): Promise<AppPermissionState>;
+    list(kind: ProviderKind, signal?: AbortSignal): Promise<ProviderDescriptor[]>;
+    private connect;
+    speechCapabilities(provider: Pick<ProviderDescriptor, "appId" | "key">, signal?: AbortSignal): Promise<SpeechCapabilities>;
+    transcribe(provider: Pick<ProviderDescriptor, "appId" | "key">, audio: Blob, options?: {
+        language?: string;
+        signal?: AbortSignal;
+    }): Promise<SpeechResult>;
+    /** User-attributed requests preserve the assistant's existing handoff and dispatch policy. */
+    assistant(provider: Pick<ProviderDescriptor, "appId" | "key">, userToken: () => Promise<string>): Promise<AssistantClient>;
+    /** Provider-side validation checks live grants on every request; never cache this result. */
+    validate(token: string, kind: ProviderKind, key?: string, signal?: AbortSignal): Promise<ProviderInvocation>;
+}

package/dist/providers-server.js

@@ -0,0 +1,78 @@
+import { AssistantClient } from "./assistant.js";
+import { ProviderError } from "./providers.js";
+/** Server-only provider client. Its app service token must never be sent to a browser or provider. */
+export class ProviderClient {
+    appId;
+    core;
+    service;
+    container;
+    constructor(options = {}) {
+        this.appId = options.appId ?? process.env.HOSTY_APP_ID ?? "";
+        this.core = new URL(options.coreOrigin ?? process.env.HOSTY_CORE_ORIGIN ?? "http://127.0.0.1:7070");
+        this.service = options.serviceToken ?? process.env.HOSTY_APP_SERVICE_TOKEN ?? "";
+        this.container = options.runningInContainer ?? process.env.HOSTY_RUNTIME_TYPE === "docker";
+        if (!this.appId || !this.service)
+            throw new ProviderError("hosty_misconfigured", "Hosty app credentials are not configured.", 503);
+    }
+    async coreRequest(suffix, body, signal, userToken) {
+        const response = await fetch(new URL(`/api/internal/apps/${encodeURIComponent(this.appId)}${suffix}`, this.core), {
+            method: body === undefined ? "GET" : "POST", redirect: "error", cache: "no-store",
+            signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000),
+            headers: { authorization: `Bearer ${this.service}`, "content-type": "application/json", ...(userToken ? { "X-Hosty-User-Token": userToken } : {}) },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        return read(response);
+    }
+    permissions(signal) { return this.coreRequest("/permissions", undefined, signal); }
+    async list(kind, signal) {
+        return (await this.coreRequest(`/providers/${kind}`, undefined, signal)).providers;
+    }
+    async connect(provider, signal, userToken) {
+        const issued = await this.coreRequest(`/providers/${provider.kind}/token`, { providerAppId: provider.appId, key: provider.key }, signal, userToken);
+        if (issued.provider.version !== 1 || !issued.provider.url)
+            throw new ProviderError("provider_incompatible", "This provider does not support interface version 1.", 409);
+        const url = new URL(issued.provider.url);
+        if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
+            throw new ProviderError("provider_url_invalid", "Invalid provider endpoint.", 409);
+        // Core's internal origin already identifies the host from this consumer's vantage point.
+        if ((this.container || this.core.hostname === "host.docker.internal") && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))
+            url.hostname = "host.docker.internal";
+        return { ...issued, url: url.href.replace(/\/$/, "") };
+    }
+    async speechCapabilities(provider, signal) {
+        const binding = await this.connect({ ...provider, kind: "speech-to-text" }, signal);
+        return read(await fetch(`${binding.url}/capabilities`, { redirect: "error", signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000), headers: { authorization: `Bearer ${binding.token}` } }));
+    }
+    async transcribe(provider, audio, options = {}) {
+        const signal = options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(300_000)]) : AbortSignal.timeout(300_000);
+        const binding = await this.connect({ ...provider, kind: "speech-to-text" }, signal);
+        const url = new URL(`${binding.url}/transcriptions`);
+        if (options.language)
+            url.searchParams.set("language", options.language);
+        return read(await fetch(url, { method: "POST", redirect: "error", signal,
+            headers: { authorization: `Bearer ${binding.token}`, "content-type": audio.type || "audio/wav" }, body: audio }));
+    }
+    /** User-attributed requests preserve the assistant's existing handoff and dispatch policy. */
+    async assistant(provider, userToken) {
+        const target = { ...provider, kind: "assistant" };
+        const binding = await this.connect(target, undefined, await userToken());
+        return new AssistantClient(binding.url, { version: binding.provider.version, capabilities: binding.provider.capabilities }, async () => {
+            const fresh = await this.connect(target, undefined, await userToken());
+            if (fresh.url !== binding.url)
+                throw new ProviderError("provider_changed", "The assistant endpoint changed. Reconnect explicitly.", 409);
+            return { token: fresh.token };
+        });
+    }
+    /** Provider-side validation checks live grants on every request; never cache this result. */
+    validate(token, kind, key = "default", signal) {
+        return this.coreRequest("/provider/introspect", { token, kind, key }, signal);
+    }
+}
+async function read(response) {
+    const body = await response.json().catch(() => null);
+    if (!response.ok)
+        throw new ProviderError(body?.code ?? "provider_failed", body?.message ?? `Provider request failed (${response.status}).`, response.status);
+    if (body === null)
+        throw new ProviderError("provider_response_invalid", "Provider returned an invalid response.", 502);
+    return body;
+}

package/dist/providers.d.ts

@@ -0,0 +1,43 @@
+/** Provider categories supported by Core. Agent execution is intentionally not part of this contract. */
+export type ProviderKind = "speech-to-text" | "assistant";
+export type ProviderDescriptor = {
+    appId: string;
+    displayName: string;
+    kind: ProviderKind;
+    key: string;
+    version: number | null;
+    capabilities: string[];
+    url: string | null;
+    available: boolean;
+};
+export type AppPermissionState = {
+    required: string[];
+    optional: string[];
+    granted: string[];
+};
+export type ProviderInvocation = {
+    callerAppId: string;
+    callerInstallation: string;
+    userId: string | null;
+    hostRole: string | null;
+    kind: ProviderKind;
+    key: string;
+};
+export type SpeechResult = {
+    text: string;
+    language?: string | null;
+};
+export type SpeechCapabilities = {
+    version: 1;
+    mediaTypes: string[];
+    maxBytes: number;
+    maxDurationSeconds: number;
+    backend: string;
+    ready: boolean;
+};
+/** Errors retain Core/provider codes so consumers can distinguish denial from unavailable service. */
+export declare class ProviderError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status: number);
+}

package/dist/providers.js

@@ -0,0 +1,10 @@
+/** Errors retain Core/provider codes so consumers can distinguish denial from unavailable service. */
+export class ProviderError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hosty-sdk/app",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "Hosty app auth: session state machine, recovery bridge, Core revalidation, and the embedder responder.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -52,6 +52,14 @@
     "./assistant": {
       "types": "./dist/assistant.d.ts",
       "default": "./dist/assistant.js"
+    },
+    "./providers": {
+      "types": "./dist/providers.d.ts",
+      "default": "./dist/providers.js"
+    },
+    "./providers/server": {
+      "types": "./dist/providers-server.d.ts",
+      "default": "./dist/providers-server.js"
     }
   },
   "scripts": {