Client

Import from @infrared-city/infrared-sdk.

AuthHeaders = Readonly<Record<string, string>>

The HTTP headers that authenticate one request.

Import from @infrared-city/infrared-sdk.

Credentials and caller identity for the client.

Provide at least one of apiKey, token or getToken. token and getToken are mutually exclusive.

Extended by

• InfraredClientConfig

Properties

Import from @infrared-city/infrared-sdk.

AuthResolver = () => Promise<AuthHeaders>

Produces the authentication headers for the next request. It is evaluated on every request, so a dynamic token is always current.

Returns

Promise<AuthHeaders>

Import from @infrared-city/infrared-sdk.

buildAuthResolver(options): AuthResolver

Build an authentication resolver that evaluates dynamic JWTs on every request.

Parameters

Returns

AuthResolver

A function that resolves the authentication headers for one request.

Throws

If token and getToken are both given, if no credential is given, or if getToken returns an empty or non-string value when the resolver runs.

Import from @infrared-city/infrared-sdk.

const consoleLogger: Logger = console

A Logger that writes to the global console.

Import from @infrared-city/infrared-sdk.

coreVersion(): string

The version of the computation core bundled with this SDK.

Call initializeCore first.

Returns

string

The version string.

Throws

when the core has not been initialised.

Import from @infrared-city/infrared-sdk.

What the first submission that refers to previously uploaded geometry settled.

acceptedJobIds are real jobs from your own run, not extra test jobs. On "supported" it is the job whose acknowledgement confirmed that the API resolves geometry references. On "unsupported" it is the job that was accepted without a valid acknowledgement; its result is discarded and it is reported here so it can be reconciled against billing.

Properties

Import from @infrared-city/infrared-sdk.

GeometryReuseProbeOutcome = "supported" \| "unsupported"

Whether the API resolved a reference to previously uploaded geometry.

"supported" means it did, "unsupported" means it did not.

Import from @infrared-city/infrared-sdk.

One geometry URL that a GeometryUrlStore keeps.

Properties

Import from @infrared-city/infrared-sdk.

A place that keeps the URLs of uploaded tile geometry for longer than one client: for example sessionStorage, IndexedDB or a file. Give the same store to a new client (a new worker, or the page after a reload) and it does not upload the same geometry again while the URL is still valid.

The SDK makes the keys and the expiresAt values: 23 hours after the upload, or the end of the signed URL when that is earlier. A key contains the gateway URLs, a SHA-256 digest of the credentials (never the credentials) and the digest of the geometry. An entry is a read link to your geometry for its lifetime; treat the store like a cache of secrets.

Methods

claim()?

optional claim(key): Promise<() => void>

Optional. Claim key for one upload across clients that share this store (several workers, tabs or processes). Resolve when this client holds the claim, and return the function that releases it. On a get miss the SDK claims the key, calls get again (another client may have uploaded it while this one waited), uploads only on a second miss, waits for set to settle, then releases (the run itself does not wait for set). An aborted run stops waiting for the claim at once; the shared upload that other runs may wait on keeps waiting, at most 60 s, and then uploads anyway (a second upload is better than a stuck run). A claim that resolves later is released at once. A claim that throws is a miss with one warning; the SDK uploads.

Parameters

Returns

Promise<() => void>

Example

Web Locks, in a page or a worker

claim: (key) => new Promise((claimed, failed) => {
  navigator.locks.request(`ir-geom:${key}`, () => new Promise<void>((release) => claimed(release)))
    .catch(failed);
}),

get()

get(key): GeometryUrlEntry \| Promise<GeometryUrlEntry \| undefined> \| undefined

Return the entry for key, or undefined when there is none.

Parameters

Returns

GeometryUrlEntry \| Promise<GeometryUrlEntry \| undefined> \| undefined

set()

set(key, url, expiresAt): void \| Promise<void>

Keep url for key until expiresAt (milliseconds since the Unix epoch).

Parameters

Returns

void \| Promise<void>

Import from @infrared-city/infrared-sdk.

The entry point of the SDK: runs analyses on one site or over a polygon area (split into tiles), and exposes the weather, buildings, vegetation, ground-material and billing services.

Constructors

Constructor

new InfraredClient(options?): InfraredClient

Creates a client; give a credential (apiKey, token, getToken or auth) here or through the environment.

Parameters

Returns

InfraredClient

Throws

when auth is combined with another credential, or INFRARED_GEOMETRY_REF_ENABLED is not a Boolean string.

Throws

when a removed option such as acquisition is passed.

Throws

when no credential is given.

Other

analyses

readonly analyses: AnalysisService

Submits requests that already use the API's own keys.

apiKey

readonly apiKey: string \| undefined

The API key the client was created with, if any.

baseUrl

readonly baseUrl: string

The API base URL in use, without trailing slashes.

billing

readonly billing: BillingService

The public price list.

buildings

readonly buildings: BuildingsService

Buildings around a site.

groundMaterials

readonly groundMaterials: GroundMaterialsService

Ground materials around a site.

jobs

readonly jobs: JobsService

Submits jobs, reads their status and downloads results.

logger

readonly logger: Logger

Where the SDK's warnings go.

vegetation

readonly vegetation: VegetationService

Trees around a site.

weather

readonly weather: WeatherService

Weather stations and data.

checkAreaState()

checkAreaState(schedule, options?): Promise<AreaState>

Reads the status of the schedule's jobs once, updates it and returns the run's counts.

Parameters

Returns

Promise<AreaState>

checkPartsState()

checkPartsState(schedule, options?): Promise<AreaState>

Reads the status of every open part once; returns the run's counts.

Parameters

Returns

Promise<AreaState>

decompressResult()

decompressResult(content): unknown

Decodes an already downloaded result archive; prefer jobs.decompress, which returns a typed result.

Parameters

Returns

unknown

generateTiles()

generateTiles(polygon, options?): Tile\[\]\[\]

Builds the tile grid covering a polygon, south to north; sends no request.

Parameters

Returns

Tile\[\]\[\]

mergeAreaJobs()

mergeAreaJobs(schedule, options?): Promise<AreaResult>

Downloads the finished grid jobs of an area run and merges them into an AreaResult. Throws when a tile did not contribute; calling it again with the same schedule completes a run whose results could not be fetched.

Parameters

Returns

Promise<AreaResult>

mergeParts()

mergeParts(schedule, options?): Promise<unknown>

Downloads and joins a finished parts run; throws AnalysisPartsError naming a failed part.

Parameters

Returns

Promise<unknown>

mergeSurfaceAreaJobs()

mergeSurfaceAreaJobs(schedule, options?): Promise<SurfaceColumns>

Downloads the finished surface jobs of an area run and joins them into SurfaceColumns.

Parameters

Returns

Promise<SurfaceColumns>

previewArea()

previewArea(polygon, options): Promise<AreaPreview>

Estimates an area run from its tile count; submits nothing. The cost is the jobs times the API's price for the analysis (pricingSource says if the price is "live", "cached" or "stale"). For a facade run use previewAreaBatches. Throws when the polygon needs more non-empty tiles than the limit.

Parameters

Returns

Promise<AreaPreview>

Throws

when the price list cannot be fetched and the client has none.

Example

const preview = await client.previewArea(polygon, { analysisType: "wind-speed" });

previewAreaBatches()

previewAreaBatches(input, polygon, options?): Promise<AreaBatchPreview>

Previews a facade run: builds the plan runArea would and reports its job count instead of submitting it. Pass the same input a runArea call would, because previewArea under-reports a facade (analysisSurfaces) run.

Parameters

Returns

Promise<AreaBatchPreview>

~~previewAreaWithPricing()~~

previewAreaWithPricing(polygon, options): Promise<AreaPreviewWithPricing>

Parameters

Returns

Promise<AreaPreviewWithPricing>

Deprecated

Use previewArea: it is priced with the same price list. Removed in 2.0.

previewParts()

previewParts(input, options?): Promise<PartsPreview>

The parts, sensors and tokens a runAndWait of input would bill; sends nothing.

Parameters

Returns

Promise<PartsPreview>

run()

run(input, options?): Promise<Job>

Submits one analysis request and returns the accepted Job without waiting; follow with jobs.waitForCompletion, or use runAndWait. Throws a TypeError straight away, before a promise is returned, when the request is not valid; later failures reject the returned promise.

Parameters

Returns

Promise<Job>

Example

const job = await client.run({ analysisType: AnalysesName.WindSpeed, ...parameters });

runAndWait()

runAndWait(input, options?): Promise<unknown>

Submits a request, waits for it and returns the decoded result. A daylight-factor request whose floors do not fit one job is sent as parts in parallel and joined into the result a single request would give (maxParts: 1 sends one job); any other request is one job. A daylight-factor result is a DaylightFactorResult, or the JSON value with resultFormat: "json".

Rejects when a job fails or the wait times out.

Parameters

Returns

Promise<unknown>

Example

const result = await client.runAndWait({ analysisType: AnalysesName.WindSpeed, ...parameters });

runArea()

Call Signature

runArea(input, polygon, options?): Promise<AreaSchedule>

Plans an area run over polygon, submits one job per non-empty tile and returns the saved AreaSchedule without waiting; finish it with checkAreaState and mergeAreaJobs.

A tile that fails does not stop the run. The tiles that went out before it may be billed. List the failed tiles in schedule.failedSubmissions and pass the schedule as retryFrom to send only those.

Give a list of inputs to run several analyses over the same polygon: they share one prepared site (and a facade tile's parts), and the call returns one schedule per input, in input order. retryFrom is refused with a list; retry each analysis alone.

Parameters

Returns

Promise<AreaSchedule>

the saved AreaSchedule with one entry for each submitted tile (one schedule per input for a list).

Throws

when the polygon needs more non-empty tiles than the limit; the message gives the maxTilesOverride to pass.

Throws

when an acquired layer was read with a narrower margin than the analysis needs.

Example

const schedule = await client.runArea(input, polygon, { maxTilesOverride: 400 });
const [solar, wind] = await client.runArea([solarInput, windInput], polygon);

Call Signature

runArea(inputs, polygon, options?): Promise<AreaSchedule\[\]>

Plans an area run over polygon, submits one job per non-empty tile and returns the saved AreaSchedule without waiting; finish it with checkAreaState and mergeAreaJobs.

A tile that fails does not stop the run. The tiles that went out before it may be billed. List the failed tiles in schedule.failedSubmissions and pass the schedule as retryFrom to send only those.

Give a list of inputs to run several analyses over the same polygon: they share one prepared site (and a facade tile's parts), and the call returns one schedule per input, in input order. retryFrom is refused with a list; retry each analysis alone.

Parameters

Returns

Promise<AreaSchedule\[\]>

the saved AreaSchedule with one entry for each submitted tile (one schedule per input for a list).

Throws

when the polygon needs more non-empty tiles than the limit; the message gives the maxTilesOverride to pass.

Throws

when an acquired layer was read with a narrower margin than the analysis needs.

Example

const schedule = await client.runArea(input, polygon, { maxTilesOverride: 400 });
const [solar, wind] = await client.runArea([solarInput, windInput], polygon);

runAreaAndWait()

Call Signature

runAreaAndWait(input, polygon, options?): Promise<SurfaceColumns \| AreaResult>

Runs an analysis over a polygon area and returns the merged result: it submits the tiles, waits, retries what failed (retries) and merges. A surface run returns SurfaceColumns, any other run an AreaResult. areaTimeout is in seconds, default 3600.

Give a list of inputs to run several analyses over the same polygon in ONE run: they share the prepared site and a facade tile's parts, and the call returns one result per input, in input order, when every analysis is finished. When one failed, the first error in input order is thrown. runAreaStream hands each result over the moment it is finished.

Parameters

Returns

Promise<SurfaceColumns \| AreaResult>

Throws

when the run does not finish within areaTimeout.

Throws

when a tile failed, a finished job did not download, or a submit is uncertain.

Throws

when a status request is refused for good (for example HTTP 403).

Throws

when areaTimeout is not a positive finite number.

Example

const result = await client.runAreaAndWait(input, polygon, { areaTimeout: 1800 });
const [solar, svf] = await client.runAreaAndWait([solarInput, svfInput], polygon);

Call Signature

runAreaAndWait(inputs, polygon, options?): Promise<(SurfaceColumns \| AreaResult)\[\]>

Runs an analysis over a polygon area and returns the merged result: it submits the tiles, waits, retries what failed (retries) and merges. A surface run returns SurfaceColumns, any other run an AreaResult. areaTimeout is in seconds, default 3600.

Give a list of inputs to run several analyses over the same polygon in ONE run: they share the prepared site and a facade tile's parts, and the call returns one result per input, in input order, when every analysis is finished. When one failed, the first error in input order is thrown. runAreaStream hands each result over the moment it is finished.

Parameters

Returns

Promise<(SurfaceColumns \| AreaResult)\[\]>

Throws

when the run does not finish within areaTimeout.

Throws

when a tile failed, a finished job did not download, or a submit is uncertain.

Throws

when a status request is refused for good (for example HTTP 403).

Throws

when areaTimeout is not a positive finite number.

Example

const result = await client.runAreaAndWait(input, polygon, { areaTimeout: 1800 });
const [solar, svf] = await client.runAreaAndWait([solarInput, svfInput], polygon);

runParts()

runParts(input, options?): Promise<PartsSchedule>

Submits a request as its parts without waiting; returns the saved PartsSchedule.

Parameters

Returns

Promise<PartsSchedule>

Run an analysis

runAreaStream()

runAreaStream(inputs, polygon, options?): AsyncGenerator<AreaStreamItem, void, undefined>

Runs analyses over one polygon area as runAreaAndWait does, and yields each result the moment its last tile is merged, in the order they finish. Read the items one by one: the SDK keeps no reference to a yielded result. A failed analysis yields an item with error; the others continue. break or options.signal cancels the analyses not yet yielded. options apply to every analysis; onProgress reports each analysis until it is finished (then its bodies are freed).

Parameters

Returns

AsyncGenerator<AreaStreamItem, void, undefined>

Throws

on the first next() when areaTimeout is not a positive finite number.

Example

for await (const item of client.runAreaStream([solar, wind], polygon)) draw(item);

Import from @infrared-city/infrared-sdk.

Settings for new InfraredClient(config). Give at least one credential: apiKey, token or getToken (inherited from the authentication options), or a custom auth.

Extends

• AuthOptions

Properties

Import from @infrared-city/infrared-sdk.

InfraredClientOptions = InfraredClientConfig

Another name for InfraredClientConfig.

Import from @infrared-city/infrared-sdk.

Environment values for InfraredClientConfig.env, for runtimes without process.env (for example Cloudflare Workers). Each value that is missing here is read from process.env when that exists.

Properties

Import from @infrared-city/infrared-sdk.

InfraredSurface = "platform" \| "webapp" \| "grasshopper" \| "revit" \| "qgis" \| "arcgis" \| "sketchup" \| "archicad" \| "script" \| "cli"

The application an SDK call is made from, sent to the API so usage can be attributed to it.

Defaults to "script" when not set on AuthOptions.

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/tiling.

initializeCore(options?): Promise<void>

Load and initialise the Infrared core (a WebAssembly module) used by the SDK's local computation.

Wait for it to finish before using operations that run in the core. Once it has succeeded, later calls resolve immediately. This entry point needs one core source (url, bytes or module); the Node entry point can also load the packaged core when none is given.

Parameters

Returns

Promise<void>

A promise that resolves when the core is ready.

Throws

If the core cannot be loaded or the options are invalid.

Throws

If the core loaded but failed its version check.

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/tiling.

Options for initializeCore().

Pass at most one of url, bytes and module to choose where the core is loaded from. The Node entry point loads the packaged core when none of them is given.

Properties

Import from @infrared-city/infrared-sdk.

Settings for constructing a JobsService.

Properties

Import from @infrared-city/infrared-sdk.

Where the SDK sends its own messages. Pass one to the client to capture or silence them.

Properties

Import from @infrared-city/infrared-sdk.

OnGeometryReuseProbe = (event) => void \| Promise<void>

A callback that receives a GeometryReuseProbeEvent. It may return a promise.

Parameters

Returns

void \| Promise<void>

Import from @infrared-city/infrared-sdk.

Options shared by the SDK's service classes.

Extended by

• WeatherServiceOptions

Properties

Import from @infrared-city/infrared-sdk.

const silentLogger: Logger

A Logger that discards every message.

Import from @infrared-city/infrared-sdk.

const VERSION: "1.1.0" = "1.1.0"

The version of this SDK package, for example "0.14.0".