@speechineer/js

The configuration and data types every Speechineer package shares. Whichever package you install, these are the same: how you configure the client, how you describe the form to fill, the callbacks that deliver values and progress, the errors and events that report problems, and the state every session reports.

The package for your framework documents its own functions; everything those functions' options are built from is described here, once.

Setup

Create the client once, at app startup, with your credentials — every session starts from it. Without a baseUrl it talks to the production Speechineer API.

SpeechineerClient

Your connection to Speechineer. Create one with createClient and keep it for the lifetime of your app; every session starts from it.

Methods

speechToForm()

speechToForm(options): SpeechToFormSession;

Fill a form by voice. Returns the session; call start() on it when the user is ready to speak. In React and Angular use useSpeechToForm / injectSpeechToForm instead — they take the same options and manage the session for you.

Parameters

Returns

SpeechToFormSession

textToForm()

textToForm(options): TextToFormSession;

Extract field values from text — no microphone involved. Returns the session; call extract(text) as often as you like. In React and Angular use useTextToForm / injectTextToForm.

Parameters

Returns

TextToFormSession

Properties

ClientOptions

How the SDK reaches Speechineer and on whose behalf. Pass it once to createClient (or to the React provider / Angular provideSpeechineer).

Fill in one of the two credential styles:

• apiKey (+ account) — for an Unsigned API key. The SDK builds the token for you. Convenient for development, but the key is readable in your frontend.
• token — for a Signed API key. Your server signs a short-lived token per user and you hand it over (a string, or a function that fetches one); the SDK forwards it untouched, because signing requires a private key that must never reach the browser. Use this in production.

Properties

DEFAULT_BASE_URL

const DEFAULT_BASE_URL: "https://ai.speechineer.com/api" = 'https://ai.speechineer.com/api';

Where the SDK sends its requests unless createClient({ baseUrl }) says otherwise — the production Speechineer API.

createClient()

function createClient(options?): SpeechineerClient;

Create the client once, at app startup, and create every session from it.

Parameters

Returns

SpeechineerClient

Example

import { createClient } from "@speechineer/js";

// Development — an unsigned workspace key + who the end user is:
const speechineer = createClient({ apiKey: "spnr_live_…", account: { key: user.id } });

// Production — your server signs a short-lived token per user:
const speechineer = createClient({ token: () => fetch("/api/speechineer-token").then((r) => r.text()) });

Authentication

Who is calling: your workspace's API key plus an identifier for the end user, or a token your server signed (a string, or a function that fetches a fresh one).

Account

The end user a session is for. Usage and per-account limits are tracked against it, so avoid one shared value for everybody.

Properties

TokenProvider

type TokenProvider = () => string | Promise<string>;

Returns a token your server signed for the current user — called every time a session is created or resumed, so a fresh, short-lived token is always used.

Returns

string | Promise<string>

Forms

Which form to fill and where its definition lives: configured in Speechineer (a workspace form — your code names it) or defined in your code (an inline form — fields, prompts, and model configurations ship with the call).

FormIdentity

The identity every form carries, whichever side defines it.

Extended by

• InlineForm
• WorkspaceForm

Properties

WorkspaceForm

A form configured in Speechineer. Your code names it, and the fields, prompts and models come from your workspace — change them there without shipping a release. Individual fields can be marked in your workspace as set by code, and those arrive through fieldConfigs.

Extends

• FormIdentity

Properties

Prompts

The prompts an inline form supplies, one per slot: how to transcribe, and how to extract the field values. Each is plain-language instruction text. Omit a slot to use the default.

Properties

Models

The model configurations an inline form pins, one per slot, by the keys you gave them in your workspace. Omit a slot to use the workspace default.

Properties

InlineForm

A form defined in your code: you declare the fields to extract (build them with FormField) and, optionally, the prompts and model configurations to use. Speechineer records it under key / version in your workspace.

Extends

• FormIdentity

Properties

FormDefinition

type FormDefinition = WorkspaceForm | InlineForm;

Where the form comes from: the one configured in Speechineer (source: 'workspace') or the one your code defines (source: 'inline'). Every capability that fills a form takes one of these as form.

Fields

What to extract and how to describe it. Build each field of an inline form with FormField; the prompt is the instruction Speechineer follows for that field.

OptionsFieldConfig

The allowed options of a choice field (select / multiselect).

Properties

RangeFieldConfig

The [min, max] range of a slider field.

Properties

FieldSpec

One field to extract. Build these with FormField rather than by hand — the factory picks the right type and validates the options for you.

Properties

FieldFactory

The field factory surface. Every helper returns a ready FieldSpec.

Methods

text()

text(id, prompt): FieldSpec;

Free-form text.

Parameters

Returns

FieldSpec

textarea()

textarea(id, prompt): FieldSpec;

Multi-line free-form text; same value semantics as text.

Parameters

Returns

FieldSpec

email()

email(id, prompt): FieldSpec;

An email address.

Parameters

Returns

FieldSpec

phone()

phone(id, prompt): FieldSpec;

A phone number.

Parameters

Returns

FieldSpec

url()

url(id, prompt): FieldSpec;

A URL.

Parameters

Returns

FieldSpec

integer()

integer(id, prompt): FieldSpec;

A whole number.

Parameters

Returns

FieldSpec

float()

float(id, prompt): FieldSpec;

A decimal number.

Parameters

Returns

FieldSpec

checkbox()

checkbox(id, prompt): FieldSpec;

A yes/no value.

Parameters

Returns

FieldSpec

date()

date(id, prompt): FieldSpec;

A calendar date.

Parameters

Returns

FieldSpec

time()

time(id, prompt): FieldSpec;

A time of day.

Parameters

Returns

FieldSpec

datetime()

datetime(id, prompt): FieldSpec;

A date with a time.

Parameters

Returns

FieldSpec

slider()

slider(
   id, 
   prompt, 
   range): FieldSpec;

Ranged numeric field; range is [min, max] with min < max.

Parameters

Returns

FieldSpec

select()

select(
   id, 
   prompt, 
   options, 
   appendOptionsToPrompt?): FieldSpec;

Single-choice; options must be non-empty.

Parameters

Returns

FieldSpec

multiselect()

multiselect(
   id, 
   prompt, 
   options, 
   appendOptionsToPrompt?): FieldSpec;

Multi-choice; options must be non-empty.

Parameters

Returns

FieldSpec

FieldConfigFactory

The factory surface for configuring a workspace form's code-defined fields. Only the three types that take a configuration appear here — the rest have nothing for code to supply.

Methods

slider()

slider(id, range): FieldSpec;

Ranged numeric field; range is [min, max] with min < max.

Parameters

Returns

FieldSpec

select()

select(
   id, 
   options, 
   appendOptionsToPrompt?): FieldSpec;

Single-choice; options must be non-empty.

Parameters

Returns

FieldSpec

multiselect()

multiselect(
   id, 
   options, 
   appendOptionsToPrompt?): FieldSpec;

Multi-choice; options must be non-empty.

Parameters

Returns

FieldSpec

FieldConfig

type FieldConfig = 
  | OptionsFieldConfig
  | RangeFieldConfig;

The extra configuration a field type may carry: the allowed options of a choice field, or the range of a slider.

FieldType

type FieldType = 
  | "text"
  | "textarea"
  | "email"
  | "phone"
  | "url"
  | "integer"
  | "float"
  | "slider"
  | "checkbox"
  | "select"
  | "multiselect"
  | "date"
  | "time"
  | "datetime"
  | "template";

FIELD_TYPES

const FIELD_TYPES: readonly ["text", "textarea", "email", "phone", "url", "integer", "float", "slider", "checkbox", "select", "multiselect", "date", "time", "datetime"];

The field types you can declare, in presentation order. Use it to build a type picker without redeclaring the list.

FormField

const FormField: FieldFactory;

Build the fields of an inline form. A factory object (no new, tree-shakeable) producing FieldSpecs, with light runtime validation for the config-bearing types.

Example

import { FormField } from "@speechineer/js"; // also exported by @speechineer/react and @speechineer/angular

const fields = [
  FormField.text("patientName", "Extract the patient full name"),
  FormField.integer("age", "Extract the age in years"),
  FormField.select("species", "Extract the species", ["Canine", "Feline", "Equine"]),
  FormField.slider("painLevel", "Extract the pain level", [0, 10]),
];

FormFieldConfig

const FormFieldConfig: FieldConfigFactory;

Configure the fields your workspace form marks as set by your code — a choice field whose options come from your own data, for example. Pass the results as the form's fields.

Same validation as FormField, without the prompt: what to extract is already written in your workspace, so only the field id and the configuration come from here.

Example

import { FormFieldConfig } from "@speechineer/js"; // also exported by @speechineer/react and @speechineer/angular

const form = {
  source: "workspace",
  key: "intake",
  version: "1",
  language: "en",
  fields: [FormFieldConfig.select("species", await loadSpeciesFromMyDatabase())],
} as const;

Callbacks

Optional hooks for imperative integrations. Everything they report — values, the transcript, events, errors — is also in the session state.

SessionCallbacks

The callbacks every session accepts. All of them are optional: a session runs without any, and you add the ones your integration reacts to. Everything they report is also visible in the session state, so a UI that renders from the state needs none of them.

Properties

FormValueCallbacks

Field-value callbacks, added by every capability that fills a form. Optional — the latest value of every field is always available as values in the session state; use the callback to push values into a form library imperatively.

Properties

TranscriptCallbacks

Transcript callbacks, added by every capability that returns the spoken text. Optional — the transcript so far is always available as transcript in the session state.

Properties

Events and errors

What you receive when something noteworthy or fatal happens during a session: a typed error with a stable code, and the stream of status events.

SpeechineerClientError

Your app's own mistake, caught before anything was sent — missing credentials, an action before start(), or a microphone the browser would not give up.

Extends

• SpeechineerError

Properties

SpeechineerAuthError

The credentials were missing, malformed, expired, or rejected.

Extends

• SpeechineerError

Properties

SpeechineerQuotaError

A usage allowance is spent. meta carries the ceiling that bound and how much of it was used — see QuotaMeta.

Extends

• SpeechineerError

Properties

SpeechineerAccessError

The credentials are valid but not allowed to do this.

Extends

• SpeechineerError

Properties

SpeechineerNotFoundError

Something named in the request does not exist — a form, a version, or a session that has expired. Distinct from SpeechineerSessionEndedError, which means it did exist.

Extends

• SpeechineerError

Properties

SpeechineerSessionEndedError

The session existed and is over. details[0] carries what ended it — a failure, or a spent allowance. Start a new session; this one cannot be resumed.

Extends

• SpeechineerError

Properties

SpeechineerConflictError

The request conflicts with the current state — for example an action whose prerequisite has not happened yet.

Extends

• SpeechineerError

Properties

SpeechineerValidationError

The request was not acceptable. details lists one atom per offending field, so a rejected form tells you everything that is wrong in one round trip.

Extends

• SpeechineerError

Properties

SpeechineerRateLimitError

Too many requests. Slow down and retry.

Extends

• SpeechineerError

Properties

SpeechineerRuntimeError

A running session stopped because something failed — transcription or field extraction could not be restarted. The session is over; offer the user a fresh start.

Extends

• SpeechineerError

Properties

SpeechineerServiceError

Speechineer could not handle the request, for a reason that is not your app's doing. Retrying the same request may work.

Extends

• SpeechineerError

Properties

SpeechineerUpstreamError

A service Speechineer depends on answered with something unusable. Retrying the same request the same way is unlikely to help.

Extends

• SpeechineerError

Properties

SpeechineerUnavailableError

Speechineer is temporarily unreachable. Nothing is wrong with your request — retry later.

Extends

• SpeechineerError

Properties

SpeechineerTimeoutError

The request took too long to complete. Retrying is reasonable.

Extends

• SpeechineerError

Properties

QuotaMeta

The meta a SpeechineerQuotaError carries: the allowance that bound, and how much of it was used.

The amounts are decimal strings, not numbers — usage is metered in fractional units and a JSON number would round them.

Properties

SessionEvent

One status event from a running session, delivered to onEvent.

Events are progress, useful for logging or a live status display: a connection re-establishing itself, a recording gesture, a connection Speechineer refused. Anything that ends the session is not an event at all — it reaches you as a typed SpeechineerError through onError and state.error, so you never have to inspect an event to find out whether the session is still alive.

Properties

SpeechineerErrorCode

type SpeechineerErrorCode = 
  | keyof typeof SDK_ERRORS
  | string & {
};

A stable identifier for what went wrong.

The union lists what this version knows about but stays open on purpose: Speechineer can name a new failure without every app upgrading first, so the type must not claim the list is closed.

EventLevel

type EventLevel = LogVerbosity;

How important an event is — from debug chatter to critical failures. Filter your logging on it.

SpeechineerError

Something Speechineer could not do.

Branch on code — it is stable — or catch a subclass to handle a whole category at once (SpeechineerQuotaError covers every way an allowance can run out). message is written for a developer, not an end user: show your own copy to the people using your app.

meta carries the data belonging to this particular failure — the numbers behind a spent allowance, for instance — and details breaks an aggregated failure into one atom per cause, which is how a rejected form reports every offending field at once.

Extends

• Error

Extended by

• SpeechineerAccessError
• SpeechineerAuthError
• SpeechineerClientError
• SpeechineerConflictError
• SpeechineerNotFoundError
• SpeechineerQuotaError
• SpeechineerRateLimitError
• SpeechineerRuntimeError
• SpeechineerServiceError
• SpeechineerSessionEndedError
• SpeechineerTimeoutError
• SpeechineerUnavailableError
• SpeechineerUpstreamError
• SpeechineerValidationError

Constructors

Constructor

new SpeechineerError(options): SpeechineerError;

Parameters

Returns

SpeechineerError

Overrides

Error.constructor

Properties

type

readonly type: string;

The category. Prefer catching the matching subclass over comparing this yourself.

code

readonly code: string;

A stable identifier for what went wrong. Branch on this, not on message.

field

readonly field: string | null;

The field this failure is about, when it is about one.

meta

readonly meta: Record<string, unknown> | null;

Data belonging to this failure — the shape depends on code.

details

readonly details: readonly ErrorDetailSdk[];

One atom per cause, when a single failure has several.

requestId

readonly requestId: string | null;

Quote this when reporting a problem — it identifies the exact request.

cause?

readonly optional cause?: unknown;

The underlying failure, when there was one.

name

name: string;

Inherited from

Error.name

message

message: string;

Inherited from

Error.message

stack?

optional stack?: string;

Inherited from

Error.stack

Session state

What a running session reports about itself — its lifecycle, its id, the last error, the latest values, the transcript, whether it is listening, and whether each of its connections is open. The same shape in every framework: read it, subscribe to it, render from it.

ConnectionState

The state of one connection.

Properties

SessionState

Everything a session reports about itself. Read it with getState(), receive it through subscribe / onStateChange, or — in React and Angular — take it from the hook / inject result. Render your UI from it. The object is immutable — every change produces a new one — so it is safe to compare by reference.

Properties

SessionStatus

type SessionStatus = "idle" | "starting" | "active" | "recovering" | "ending" | "failed";

Where the session is in its life.

• idle — nothing started yet (or the session was ended).
• starting — the session is being created and its connection opened.
• active — the session exists; isListening and connections tell you what it is doing.
• recovering — the session vanished on the server and is being resumed.
• ending — end() is discarding the session.
• failed — starting or recovering threw; see error. start() may be called again.

ConnectionStatus

type ConnectionStatus = "closed" | "connecting" | "open" | "closing";

Whether one connection of the session is open. closing is reported by the microphone connection between stop() and the moment capture has fully wound down.

ConnectionKey

type ConnectionKey = "session" | "audio" | "results" | "transcript";

The connections a session may have. session is the main connection every session has — when it is lost, every other connection is closed as well. audio carries the microphone, results the recognized values, transcript the spoken text. A session only lists the connections its capability uses.

SessionConnections

type SessionConnections = {
  session: ConnectionState;
} & Readonly<Partial<Record<Exclude<ConnectionKey, "session">, ConnectionState>>>;

The connections of a session: session always, the others only when the capability uses them.

Type Declaration