JavaScript

bigstate.client.javascript exposes two HTTP clients. BigStateHttpClientExtended stores the host and credentials from the constructor. Each method then sends those credentials with the id and body you pass.

The base class is BigStateHttpClient. It takes a full request on every call and does not store credentials. Those calls are documented on each API reference page.

Field lists for a body or query stay on the linked API page.

HTTP

new BigStateHttpClientExtended(options)

Install#

npm
```
npm install bigstate.client.javascript
```

constructor(options)#

RequiredOptional

Create the client once. Assign client.apiKey, client.token, client.edgeSign, or client.requestSign later to replace the stored value. Assign undefined to edgeSign or requestSign to clear it.

baseUrlstring
Required
HTTP API host without `/v1`. The client appends `/v1` on each call.
example: https://api.bigstate.dev
apiKeystring
Optional
Stored and sent as `x-api-key` on later calls. Provide `apiKey` or `token`.
example: YOUR_API_KEY
tokenstring
Optional
Stored and sent as `x-token` on later calls. Provide `apiKey` or `token`.
edgeSignobject
Optional
Edge signature stored for later calls. Used when `requestSign` is not set.
- edgeSign.signaturestring
  Required
  Sent as `x-bs-edge-sign`.
- edgeSign.noncestring
  Required
  Sent as `x-bs-edge-sign-nonce`.
- edgeSign.timestampstring
  Required
  Sent as `x-bs-edge-sign-ts`.
requestSignobject
Optional
Request signature stored for later calls. When `signature` and `publicKey` are both set, this is sent instead of `edgeSign`.
- requestSign.signaturestring
  Required
  Sent as `x-bs-sign`.
- requestSign.publicKeystring
  Required
  Sent as `x-bs-sign-public-key`.
- requestSign.noncestring
  Required
  Sent as `x-bs-sign-nonce`.
- requestSign.timestampstring
  Required
  Sent as `x-bs-sign-ts`.
errorHandlerany
Optional
Optional function `(error) => error`. Receives `{ error: { code, message } }` for a failed call and may return a replacement. The last handler set by any extended client is used for every extended call in the process.

How a call is built#

The client appends /v1 to baseUrl. A method argument that names a resource becomes the query (object, principal, policy, or delivery). A write method’s next argument is the JSON body. List methods take an optional query such as pattern and next.

Stored credentials are added as headers. apiKey is x-api-key. token is x-token. One signature is sent: when requestSign.signature and requestSign.publicKey are both set, the request signature headers are used. Otherwise the edge signature headers are used.

A 2xx response is { data }. A 204 is { data: null }. Any other status is { error: { code, message } }, passed through errorHandler when one was set. client.api is the base BigStateHttpClient for a call the extended client does not wrap.

Methods#

Method names match the base BigStateHttpClient and the API reference: objectUpsert, stateUpsert, deliveryUpsert, and the rest. Pass the resource id and body as arguments. Field lists stay on the matching API page.

stateGet takes { object, version? }. contextGet() returns the caller for the stored credential. ownerCreate(edgeSign) sends the edge signature you pass in and does not use the stored API key. SignatureUtility in the same package builds the nonce and timestamp for that call: generateNonce() and generateTimestamp(). See Register.

Example#

Create the client once, then pass the object name and body.

Publish state


import { BigStateHttpClientExtended } from 'bigstate.client.javascript';

const client = new BigStateHttpClientExtended({
  baseUrl: 'https://api.bigstate.dev',
  apiKey: process.env.BIGSTATE_API_KEY,
});

const objectName = 'quickstart:counter@YOUR_OWNER';

await client.objectUpsert(objectName, { type: 2 });

const published = await client.stateUpsert(objectName, {
  value: { count: 1 },
});

console.log(published.data);

Client libraries WebSocket

Install
constructor(options)
How a call is built
Methods
Example