Documentation

Class

InsightsService

InsightsService(tokenSource, serviceUrl, scopeopt)

Client for the Scenid Insights Service.

Provides access to data sources and their documents via a factory pattern: call Source(nameOrId) to get a scoped handle for a specific source, then use the returned object's methods to query or mutate documents.

Source names (e.g. 'Orders') are resolved to their sourceId automatically using a per-service-URL cache backed by GET /api/v2/source. The cache is populated on first use and refreshed after 5 minutes or on a cache miss.

Obtained via sdk.asAdmin().Insights() or sdk.asUser(idToken).Insights().

Constructor

# new InsightsService(tokenSource, serviceUrl, scopeopt)

Parameters:
Name Type Attributes Description
tokenSource string | function
serviceUrl string
scope Object <optional>
scoped boolean <optional>

When true (set by sdk.asScript()), this client is hard-locked to whatever sourceId/permissions the current token's own claims say — never a separately-supplied value, so scoping can't drift from what the token actually grants. Source(nameOrId) ignores name resolution entirely and throws if called with any id other than the token's sourceId; Sources(...) (cross-source read) is disabled; write methods (push, Doc.create/update/delete/batchInsert) throw unless the token's permissions claim includes 'write' — unless the token also carries a dryRun claim (minted for test runs), in which case those calls are mocked instead of throwing: no request is sent, and the returned result is { dryRun: true, wouldSend: <payload> } (payload capped by ../truncate.js) rather than a real server response.
throwOnError boolean <optional>

Forwarded to ScenidCloudService — see its constructor docs. sdk.asScript() sets this, so a rejected call (e.g. a permission or auth mismatch the client-side checks above didn't already catch) throws instead of silently resolving as { status, result } with nothing written.

View Source services/InsightsService.class.js, line 36

Example
const insights = sdk.asAdmin().Insights()

// Read source metadata by name
const { result } = await insights.Source('Orders').get()

// Create a document
await insights.Source('Orders').Doc.create({ temperature: 21.5, unit: 'C' })

Extends

Methods

# Source(nameOrId) → {SourceHandle}

Returns a scoped handle for the given source, identified by name or sourceId.

The name is resolved to a sourceId via a local cache on first call. If the name is not found in the cache, the cache is refreshed once before falling back to using the value as-is.

Parameters:
Name Type Description
nameOrId string

The source's human-readable name (e.g. 'Orders') or raw sourceId.

View Source services/InsightsService.class.js, line 75

SourceHandle
Example
const src = insights.Source('Orders')
const { result } = await src.get(true)  // include formulator schema

# Sources(namesOrIds) → {Object}

Returns a handle for fetching documents across multiple sources at once.

Source names (e.g. ['Orders', 'Inventory']) are resolved to sourceIds via the local cache. Results are grouped by source name in the response.

Parameters:
Name Type Description
namesOrIds Array.<string>

List of source names or sourceIds.

View Source services/InsightsService.class.js, line 283

Object
Example
const { result } = await insights.Sources(['Orders', 'Inventory'])
  .Docs.find({ humanId: 'HT-4d44d' })
// result.total, result.Orders, result.Inventory

# delete(call, bodyopt) → {Promise.<ServiceResponse>}

Sends an authenticated DELETE request.

Parameters:
Name Type Attributes Description
call string

Path relative to serviceUrl.
body * <optional>

Optional request body, serialised to JSON.
Overrides:

View Source services/ScenidCloudService.class.js, line 197

Promise.<ServiceResponse>

# get(call) → {Promise.<ServiceResponse>}

Sends an authenticated GET request.

Parameters:
Name Type Description
call string

Path relative to serviceUrl.
Overrides:

View Source services/ScenidCloudService.class.js, line 167

Promise.<ServiceResponse>

# async makeRequest(method, call, bodyopt) → {Promise.<ServiceResponse>}

Makes an authenticated HTTP request to the service and returns the parsed response.

Acquires a token, constructs the full endpoint URL, serialises the body as JSON when provided, and parses the JSON response. Throws a typed error on network failure or non-JSON responses.

Parameters:
Name Type Attributes Description
method string

HTTP method (GET, POST, PUT, or DELETE).
call string

Path to call relative to serviceUrl (leading / optional).
body * <optional>

Request body. Serialised to JSON unless already a string.
Overrides:

View Source services/ScenidCloudService.class.js, line 86

sdk/fetch-failed – network-level failure.

Error

sdk/endpoint-invalid – service returned 404 with non-JSON body.

Error

sdk/non-json-response – response body could not be parsed.

Error

Only when constructed with throwOnError: true — a non-2xx response throws instead of resolving. The message is the server's own result.error when present (a bare namespace/reason code, same convention as every other error this SDK throws), falling back to sdk/request-failed. The response status is attached as .status on the thrown Error, for a caller that wants it.

Error
Promise.<ServiceResponse>

# post(call, bodyopt) → {Promise.<ServiceResponse>}

Sends an authenticated POST request.

Parameters:
Name Type Attributes Description
call string

Path relative to serviceUrl.
body * <optional>

Request body, serialised to JSON.
Overrides:

View Source services/ScenidCloudService.class.js, line 187

Promise.<ServiceResponse>

# put(call, body) → {Promise.<ServiceResponse>}

Sends an authenticated PUT request.

Parameters:
Name Type Description
call string

Path relative to serviceUrl.
body *

Request body, serialised to JSON.
Overrides:

View Source services/ScenidCloudService.class.js, line 177

Promise.<ServiceResponse>