JavaScript Quickstart

# JavaScript Quickstart

Choose [Task Voice](#javascript-task-voice) for explicit audio input and a Task
result, or [Realtime RTC](#javascript-realtime-rtc) for live publications and
subscriptions. Both use the OneSay JavaScript SDK; their lifecycles are separate.
The package is currently a private, non-publishable local candidate.

## JavaScript + Task Voice

Start with the [installed public Task sample](#public-task-sample-using-the-installed-package)
and its three-file consumer layout below. It reuses
`runPublicTaskSample(input, ports)` from
`examples/javascript-quickstart/public-task.mjs`. For application admission,
`runAuthorizedTaskSample(input, ports)` in
`examples/javascript-quickstart/authorized-task.mjs` composes the existing
public APIs and explicit Consent decisions; the
[authorization walkthrough](#application-authorization-through-existing-public-apis)
lists its inputs.

Install the locally built `@onesay/sdk` tarball using the existing layout and
reviewed dependency closure. `corepack pnpm sdk:package:check` builds it
reproducibly as `.build/e7-javascript-package/onesay-sdk-0.0.0-e7-local.tgz`;
place it next to the consumer `package.json`, depend on
`"@onesay/sdk": "file:./onesay-sdk-0.0.0-e7-local.tgz"` as
`examples/javascript-quickstart/package.json` does, and install with
`pnpm install --ignore-scripts`. The repository proof
`corepack pnpm developer-platform:javascript-quickstart:run` does the same with
`--offline` and a prepared store. Supply current Project/Environment and Source
bindings, short-lived credentials through the existing token providers, and
already captured 16 kHz mono PCM s16le. The Task client owns WSS/OSAF framing,
sequence, ACK, backpressure, replay/resume and cancellation; it does not capture
audio or request microphone permission. A neutral Room resource used by Task
admission does not start a LiveKit session or RTC Agent.

The source-bound installed-sample results below retain their original local
fixture scope and deterministic Provider. This guide update does not rerun them.
Real Provider, Staging, Production and physical audio qualification remain
**NOT-RUN** here. The older synthetic protocol walkthrough is preserved below
as separate evidence, not proof of the installed public Task chain.

## JavaScript + Realtime RTC

Use the existing browser consumer in `examples/javascript-rtc/`. Its
`sample.mjs` exports `createRTCExample`; the page consumes an installed
`@onesay/sdk` tarball and uses the public `client.rtc.connect` facade. From the
repository, the existing launcher builds and installs that private candidate
in a fresh directory, serves it on loopback and prints its URL:

```text
node tools/rtc/run-public-example.mjs
```

This needs the repository's locked Node/pnpm toolchain and populated offline
dependency store. The launcher owns its temporary install and bounds the
demonstration to 15 minutes; Ctrl+C closes it. No registry publication or API
proxy is created. The full operation examples are in
`examples/javascript-rtc/README.md`.

Opening the page is only a local preview. Its configured SDK environment is
`staging`: an actual connection needs an already authorized environment,
application origin allowed by Control CORS, existing Room/AppSession/Source
resources and a short-lived Human/AppSession token. The page keeps the token
in memory; never supply a Platform API key or Provider key. Without these
inputs, read the example locally and leave connection qualification
**NOT-RUN — requires authorized Staging environment**.

Connect with an explicit initial receive set, then request publication and
playback through the named controls. Empty subscriptions deny all reception.
RTC connect does not create a Task or Agent; Agent creation and stop are
separate authorized operations. Local close does not prove effective server
revoke. Existing installed-browser/native receipts remain attached to the
original example sources, not this documentation change. Real Provider,
Production and hardware qualification are **NOT-RUN** by this guide.

## Historical E9 synthetic Quickstart

The following E9 result describes its original synthetic fixture scope. It does
not qualify the public Task sample documented separately below.

Status: `LOCAL SYNTHETIC PATH PASS / STAGING NOT EXECUTED`

1. Choose the Test Project Environment.
2. In a browser, provide a short-lived access token through `tokenProvider`;
   never embed an `osp_*` credential.
3. Plan a Room creation request through the generated Control contract.
4. Exchange the implemented Control API for a single-use Realtime ticket.
5. Connect with `onesay.realtime.v1`, open an Audio SignalStream, and send caller-supplied
   16 kHz mono PCM16LE frames. An AudioWorklet is an optional caller-owned capture
   method; the Task SDK does not capture audio or request microphone permission.
6. Retain frames until contiguous ACK, then wait for terminal Task state.

The repository includes an executable, empty-repository proof for the canonical
Realtime portion of this guide. Run its native host proof only in the existing
Linux fixture; do not run it on Windows:


```text
corepack pnpm developer-platform:javascript-quickstart:run
```

The proof builds the deterministic private `@onesay/sdk` candidate and an exact
`ws@8.21.3` transport archive, initializes a new empty Git repository, and
installs them with scripts disabled and a new isolated pnpm store. The OneSay
package retains its pinned internal LiveKit dependency. The proof also prepares
local archives for its complete installed, lock-bound dependency closure,
including required peers and locked optional dependencies; it never fetches
missing packages. Missing inputs or conflicting versions/peer contexts fail
before installation. Consumer-local overrides select those archives without
changing the product package or upstream manifests. The receipt records lock,
manifest and archive hashes; a repacked archive is not claimed to match the
original registry integrity value.

It then runs one complete dictation against the ephemeral loopback
Go fixture. The observed order is `task.started`, `audio.ack`,
`artifact.delta`, followed by the client `signal.end` and the server sequence
`signal.ended`, `artifact.finalized`, `task.completed`; the canonical flow's
`audio.ack` through `task.completed` events therefore remain in their exact
authority order. A second SDK client reuses the consumed ticket while the first
connection is still valid and receives the server's `1008 ticket_invalid`
close.

The SDK proof uses a synthetic server with explicit Connection, Task and Signal
ports. Its Signal port validates the complete canonical command and rejects
delegated selection and protected replay; it provides no Consent authority.
This proof does not qualify server authorization or durable Signal registration.
Those require the separate real public API and PostgreSQL product tests. The
receipt binds both the host and shared Signal fixture sources by digest.

The `PASS_LOCAL_SYNTHETIC` application receipt uses closed schema v2: bounded
scalars, digests and one event-name array only. The runner additionally records
the offline dependency closure and provenance. Its network policy is
`OFFLINE_LOCAL_ARCHIVES_AND_EXACT_IPV4_LOOPBACK`: package installation and the
Go fixture build fail closed in offline mode, and the application URL is the
exact numeric loopback endpoint `ws://127.0.0.1:<ephemeral>/v1`. Raw PCM,
transcript text, tickets, user content and device identifiers are neither
printed nor persisted. Child processes have bounded time/output and confirmed
process-tree cleanup; failure messages expose only byte counts and SHA-256
digests, never raw child output.

This proves the configured topology and fail-closed policy; it is not an
operating-system traffic observation. The receipt therefore keeps
`external_network_observation` at `NOT_EXECUTED` and does not claim measured
zero external traffic.

This is local synthetic conformance, not the external five-minute path. Control
API ticket exchange, deployed Staging, provider behavior and public package
installation remain **NOT EXECUTED** until their separate approvals and
infrastructure exist.

## Public Task sample using the installed package

Original composition-entry checkpoint: `VERIFIED_SELECTED_LOCAL_PUBLIC_TASK_SAMPLE`.
The [source-bound receipt](../development/evidence/m1-v3-gx17-public-task-8c00deb7.json) records the installed Linux public sample and existing Usage roots (2 pass, 0 fail, 0 skip), with independent local SQL assertions and confirmed cleanup. The historical E9
synthetic result above remains separate historical evidence. Staging, Production,
cloud, hardware and real Provider qualification remain `NOT-RUN`.

The new entry is
[`runPublicTaskSample(input, ports)`](../../examples/javascript-quickstart/public-task.mjs).
It imports the public `@onesay/sdk` entry. It does not provision an identity,
Project Environment, Room, Source, Consent or Grant, and it does not issue its
own connection ticket. The caller must already hold authorized resource IDs
and a fresh single-use ticket for the intended Room and Project Environment.
Room authority is carried by that server-issued ticket; this function does not
take a separate `roomId` argument or decode the ticket to authorize itself.

### Prepare the three-file consumer layout

Use a separate consumer with the approved private OneSay tarball already
installed as its `@onesay/sdk` dependency, including its declared dependency
closure. The private candidate is not a published registry release. Do not
substitute a workspace alias or delete LiveKit dependencies to claim isolation.
Installation remains the existing package workflow; this sample adds no installer.

Copy exactly these three repository files into the consumer. The two support
files reuse the existing observation logic without changing their bytes:

| Repository source | Consumer destination |
| --- | --- |
| `examples/javascript-quickstart/public-task.mjs` | `public-task.mjs` |
| `tools/capacity/pcm-session.mjs` | `support/pcm-session.mjs` |
| `tools/capacity/task-usage-readback.mjs` | `support/task-usage-readback.mjs` |

For example, on Linux, after setting `PLATFORM_REPO` and `CONSUMER` to the
intended repository and separate installed consumer:

```sh
mkdir -p "$CONSUMER/support"
cp "$PLATFORM_REPO/examples/javascript-quickstart/public-task.mjs" "$CONSUMER/public-task.mjs"
cp "$PLATFORM_REPO/tools/capacity/pcm-session.mjs" "$CONSUMER/support/pcm-session.mjs"
cp "$PLATFORM_REPO/tools/capacity/task-usage-readback.mjs" "$CONSUMER/support/task-usage-readback.mjs"
```

The consumer layout is:

```text
consumer/
  package.json
  node_modules/@onesay/sdk/
  public-task.mjs
  support/
    pcm-session.mjs
    task-usage-readback.mjs
```

The raw repository `public-task.mjs` is not a standalone checkout entry:
its relative support imports become available through this three-file layout.
The local qualification helper
`stagePackedTaskQuickstart` performs the same byte-exact staging and verifies
the resolved package root, entry, installed package and support hashes before
execution and after cleanup. That helper is a test fixture, not a new public
SDK API or an installation command.

### Call the actual exported function

The following is application glue stored next to `public-task.mjs`. Its
parameters are values supplied by your authorized application; no token is
embedded or printed. `observeAuthorizedTask` below is this guide's wrapper,
not an additional OneSay SDK export.

```js
import { buildRealtimeConnectPlan } from "@onesay/sdk";
import { runPublicTaskSample } from "./public-task.mjs";

export async function observeAuthorizedTask({
  projectId,
  environmentId,
  sourceId,
  issuedSingleUseTicket,
  signal,
  ports,
}) {
  return runPublicTaskSample(
    {
      projectId,
      environmentId,
      sourceId,
      plan: buildRealtimeConnectPlan("staging", issuedSingleUseTicket),
      signal,
      timeoutMs: 5000,
    },
    ports,
  );
}
```

`buildRealtimeConnectPlan(environment, ticket)` is the existing public SDK
function. It plans the canonical WSS connection and performs no ticket exchange.
The sample's current Usage observer addresses the canonical Staging Control
environment; this example is not a general Production endpoint configuration.
Only execute against an environment you are authorized to use. Local
qualification supplies owned loopback transports separately.

All four ports are required application callbacks, not invented SDK methods:

| Port | Actual callback shape and responsibility |
| --- | --- |
| `webSocketFactory` | `(url, protocols, options) => socket`. Return the SDK-compatible WebSocket transport. Honor the supplied connection and size bounds, disable redirects, and do not relax certificate/hostname validation for real environments. |
| `confirmedControlsFactory` | `(client, { signal }) => controls`, or a Promise of controls. Integrate the application's explicit authorized Grant/Consent selection using the existing public contracts; never default to approval or copy the fixture's synthetic Owner behavior. |
| `readbackTokenProvider` | `({ signal }) => shortLivedToken`, or a Promise of that token. Supply a current principal authorized to read the Task and Usage in the requested scope. No long-lived platform or Provider secret belongs here. |
| `readbackTransport` | `(url, init) => Promise<Response>`. Provide a Fetch-compatible transport, honor `init.signal`, and preserve the SDK's headers, no-redirect policy and scope. Loopback rewriting is a local fixture concern only. |

The controls returned by `confirmedControlsFactory` must implement the existing
observer port shape:

```text
send(type, data, messageId, { signal })
flush({ signal })
observe(event, { signal })
```

`send` and `flush` may return Promises; `observe` is a synchronous event
observer. Consent selection is an explicit application decision backed by server
authority. Returning these methods does not grant permission: the server still
validates the ticket, Source, Action, Grant and Consent. The local product
fixture's provisioning and synthetic Owner approvals remain outside the public
sample.

### PCM, completion and failure behavior

This sample generates exactly two 640-sample PCM16LE mono frames at 16 kHz:
80 ms of fixed synthetic input. It deliberately probes bounded backpressure
and replays the first unacknowledged frame through the existing SDK. Duplicate
replay is not new audio input or a second Task. There is no microphone capture,
AudioWorklet, OS dependency or media permission request in the sample.

For an application that records live audio, capture and permissions are caller
responsibilities. An AudioWorklet is one optional acquisition technique.
The Platform test-support capture controller and worklet under
`tests/browser/e7-audio-worklet/` are not product SDK exports; the package has
no `./audio-worklet` export. This Task PCM boundary does not change RTC
`publishMicrophone` behavior.

The sample waits for contiguous ACK, terminal Task/Artifact correlation, and
bounded public Task/Usage readback. It returns count-only observations with
`status: "OBSERVED_PUBLIC_TASK_SAMPLE"`,
`acceptance: "NOT_EVALUATED"` and
`cleanup: "OBSERVED_CLIENT_CLOSED"` only after the SDK observes transport
closure. That object is not proof of durable billing or server authorization.

HTTP 401/403 is terminal for this invocation and is not automatically retried.
Missing, duplicate or foreign-scope Usage, wrong Task/Artifact correlation,
missing ACK, caller cancellation, deadline expiry and failed cleanup reject
the invocation. Obtain fresh authorization through the application's explicit
flow before considering another invocation; do not replay a consumed ticket.

`timeoutMs` bounds the operation and separately bounds waiting for close.
The sample propagates abort to asynchronous factory/control/token/HTTP ports.
A callback must honor its supplied signal and release its own resources.
Bounded waiting cannot forcibly stop an uncooperative callback or undo its
external side effects; synchronous callbacks must also avoid blocking the
event loop. Never log the plan URL, ticket, token, raw PCM or transcript to
diagnose a failure.

### Qualification scope and Linux execution

Native Go/host/PG/Redis/WSS qualification runs only in the existing isolated
Linux fixture. Do not invoke the native Quickstart proof on Windows.
The selected root is `TestJavaScriptQuickstartPublicTaskUsage`; it requires the
explicit installed-consumer locator `ONESAY_TEST_TASK_PACKED_CONSUMER` and
owned loopback PostgreSQL/Redis. The Go fixture passes
`ONESAY_TEST_TASK_PUBLIC_QUICKSTART=1` only to its selected child.
Missing prerequisites produce SKIP or failure, never PASS. The default
`TestCapacityPublicTaskUsageReadback` path retains its existing behavior.

Keep three evidence scopes separate:

- The package consumer uses actual tarball members with injected protocol and
  HTTP responses. It tests sample composition, authorization-denial handling,
  bounded callbacks and cleanup; it is not a real server or billing proof.
- The staging helper's negative tests use synthetic package bytes to reject
  package-entry redirection or support drift. They do not qualify product SDK
  execution.
- The separate Linux product root uses the actual installed package, real local
  PostgreSQL/Redis, existing public Control/Realtime services and an independent
  SQL oracle. Its source-bound local result is **PASS** for the two selected roots. Local fixture TLS and a deterministic Provider do
  not establish public cloud TLS, real Provider behavior, physical hardware,
  Staging deployment or Production qualification.

### Application authorization through existing public APIs

`runAuthorizedTaskSample(input, ports)` in
`examples/javascript-quickstart/authorized-task.mjs` is the application example
that obtains its own connection material and explicitly confirms protected
operations. It composes `runPublicTaskSample`; it does not replace the SDK's
Task lifecycle, ACK, replay, backpressure or cancellation logic. This is an
example export, not a new OneSay SDK API.

Add two files to the three-file consumer layout above:

| Repository source | Consumer destination |
| --- | --- |
| `examples/javascript-quickstart/authorized-task.mjs` | `authorized-task.mjs` |
| `tools/mock-device/confirmed-controls-core.mjs` | `support/confirmed-controls-core.mjs` |

The second helper is the existing bounded confirmed-command queue, extracted
unchanged from the fixture. It does not contain the fixture's automatic Allow
selector. The original three files and the installed `@onesay/sdk`
remain required. No repository source SDK import is used.

```js
import { runAuthorizedTaskSample } from "./authorized-task.mjs";

export async function runApplicationTask(resources, signal, ports) {
  return runAuthorizedTaskSample({
    organizationId: resources.organizationId,
    projectId: resources.projectId,
    environmentId: resources.environmentId,
    deviceId: resources.deviceId,
    roomId: resources.roomId,
    sourceId: resources.sourceId,
    signal,
    timeoutMs: 60000,
    delegationTtlSeconds: 120,
  }, ports);
}
```

All resources must already exist in the intended environment. Provisioning,
login, Device registration, credentials and capability policy remain owned by
the application's existing authorized flows. This example does not create
Grants, change permissions or grant itself access.

| Application port | Responsibility |
| --- | --- |
| `humanTokenProvider({ signal })` | Supply a current short-lived Human token authorized for the public reads, Delegation management and interactive Consent decisions. |
| `deviceTokenProvider({ signal })` | Supply a separate current short-lived Device token for the intended Device. Do not substitute the Human token or pass the Device's long-lived bootstrap secret. |
| `confirmConsent(snapshot, { signal })` | Display the validated, immutable server presentation and return only `"allow"` or `"deny"` after the user's explicit decision. Honor cancellation. Never default to Allow. |
| `fetch(url, init)` | Preserve the existing SDK's request headers, scope, abort signal and redirect restrictions. |
| `webSocketFactory(url, protocols, options)` | Supply the existing compatible transport with certificate/hostname checks and bounded connection options. |

The application must implement those callbacks. The confirmation callback
provides UX only: a compatible third-party client receives exactly the same
server-side checks. Interactive Consent also requires a trusted, signed OIDC
client identity recognized by the server; being an Owner, returning `"allow"`
or inventing an Origin header cannot replace it. This Node example does not
add an Origin header. The application's browser login and CSRF requirements
still belong to its established browser flow.

The example reads `/me` and the Project, Environment, Device, Room and Source
through existing public Control operations. The Human token performs those
reads; the Device token requests the connection. After joining, the example
reads the observed Participant to check that it belongs to the configured
Device before sending the protected action. These observations do not replace
the server's current authorization checks.

For each protected command the example explicitly confirms the exact
Delegation management action and the exact Device action. Both confirmations
use the existing public Consent helpers and server snapshots, digests,
wording versions and execution bindings. A per-invocation command identity
stays identical between confirmation and the actual wire send. A rejected,
expired, changed or mismatched confirmation stops the invocation.

The connection response's `websocket_url` contains the short-lived ticket.
There is no invented separate response `ticket` or AppSession field. The
example validates the canonical URL through `buildRealtimeConnectPlan` and
does not rewrite it. The sample retains the existing Staging endpoint scope;
local qualification uses explicit owned fixture transports. It does not
authorize a Staging or Production deployment.

Success remains an observation with `acceptance: "NOT_EVALUATED"`. The
count-only `authorization_observation` records which public checks occurred;
it is not an authorization certificate. The client waits for transport
cleanup, but created server Delegations remain until their bounded expiry or
a separately confirmed revocation. Client close does not revoke a Delegation.
The default and maximum requested Delegation TTL is 120 seconds; no cleanup
step automatically approves a revocation.

Normal identity, scope, HTTP 401/403, rejected Consent, expiry, deadline and
transport failures reject the invocation without automatic retry. Public
errors use fixed stage messages and preserve only supported SDK error metadata;
they omit original causes, tokens, ticket URLs, resource IDs, presentation
content and provider details. Use the bounded operation's application context
to decide the next explicit action. Never dump transport errors or credentials.

The overall authorization and Task operation shares the caller's cancellation
and deadline. The existing sample separately bounds its close wait. Ports must
honor abort; bounded waiting cannot undo an already accepted server operation
or forcibly stop an uncooperative callback. If failure follows creation of a
Delegation, its bounded TTL still applies; failure is not evidence of revocation.

Selected qualification: **VERIFIED_LOCAL_INSTALLED_PUBLIC_TASK_SAMPLE**. [Source-bound evidence](../development/evidence/m1-v3-gx17-authorized-task-41a45efb.json) records Node29/0/0 and 31/0/0 qualified Linux events: 28 from two narrow Consent selections plus three freshly executed installed Task/Usage roots at identical product source bytes. Five earlier native batches remain FAIL with their original bindings: the fourth had passing Go tests but failed receipt parsing; the fifth passed the authorized root then failed public-example staging because the runner retained the exclusive staging directory. Both are archived separately, and their passing SDK events are not counted twice. The final flow includes two explicit fixture Consent decisions and GET readbacks. It is local qualification with a deterministic Provider, owned WSS and loopback Control HTTP; real Provider, Staging, cloud, Production and hardware remain NOT-RUN. The minimal server Consent read correction reuses existing management read authority; no new authentication or SDK API is introduced.