View as Markdown llms.txt

Client

AuthHeaders

Import from @infrared-city/infrared-sdk-ts.

AuthHeaders = Readonly<Record<string, string>>

The HTTP headers that authenticate one request.

AuthOptions

Import from @infrared-city/infrared-sdk-ts.

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

Property	Modifier	Type	Description
`apiKey?`	`readonly`	`string`	API key, sent in the `X-Api-Key` header on every request.
`getToken?`	`readonly`	() => `string` \| `Promise`<`string`>	Returns the bearer token, called before every request so a refreshed token is picked up. Must return a non-empty string.
`surface?`	`readonly`	`InfraredSurface`	The application the calls come from. Defaults to `"script"`.
`token?`	`readonly`	`string`	A fixed bearer token (JWT), sent in the `Authorization` header.

AuthResolver

Import from @infrared-city/infrared-sdk-ts.

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>

buildAuthResolver

Import from @infrared-city/infrared-sdk-ts.

buildAuthResolver(options): AuthResolver

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

Parameters

Parameter	Type	Description
`options`	`AuthOptions`	The credentials to use; see AuthOptions.

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.

consoleLogger

Import from @infrared-city/infrared-sdk-ts.

const consoleLogger: Logger = console

A Logger that writes to the global console.

coreVersion

Import from @infrared-city/infrared-sdk-ts.

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.

GeometryReuseProbeEvent

Import from @infrared-city/infrared-sdk-ts.

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

Property	Modifier	Type	Description
`acceptedJobIds`	`readonly`	readonly `string`[]	Ids of the jobs that were accepted by this submission.
`outcome`	`readonly`	`GeometryReuseProbeOutcome`	Whether the API resolved the geometry reference.

GeometryReuseProbeOutcome

Import from @infrared-city/infrared-sdk-ts.

GeometryReuseProbeOutcome = "supported" | "unsupported"

Whether the API resolved a reference to previously uploaded geometry.

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

GeometryUrlEntry

Import from @infrared-city/infrared-sdk-ts.

One geometry URL that a GeometryUrlStore keeps.

Properties

Property	Modifier	Type	Description
`expiresAt`	`readonly`	`number`	When the SDK stops using the URL, in milliseconds since the Unix epoch.
`url`	`readonly`	`string`	The signed URL of the uploaded geometry.

GeometryUrlStore

Import from @infrared-city/infrared-sdk-ts.

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

get()

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

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

Parameters

Parameter	Type
`key`	`string`

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

Parameter	Type
`key`	`string`
`url`	`string`
`expiresAt`	`number`

Returns

void | Promise<void>

InfraredClient

Import from @infrared-city/infrared-sdk-ts.

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

Parameter	Type	Description
`options`	`InfraredClientConfig`	See `InfraredClientConfig`.

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.

Properties

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.

Methods

checkAreaState()

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

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

Parameters

Parameter	Type
`schedule`	`AreaSchedule`
`options`	`CheckAreaStateOptions`

Returns

Promise<AreaState>

checkPartsState()

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

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

Parameters

Parameter	Type
`schedule`	`PartsSchedule`
`options`	`CheckAreaStateOptions`

Returns

Promise<AreaState>

decompressResult()

decompressResult(content): unknown

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

Parameters

Parameter	Type
`content`	`Uint8Array`

Returns

unknown

generateTiles()

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

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

Parameters

Parameter	Type
`polygon`	`Polygon`
`options`	{ `analysisType?`: `string`; `maxTilesOverride?`: `number`; }
`options.analysisType?`	`string`
`options.maxTilesOverride?`	`number`

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

Parameter	Type
`schedule`	`AreaSchedule`
`options`	`AreaMergeOptions`

Returns

Promise<AreaResult>

mergeParts()

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

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

Parameters

Parameter	Type
`schedule`	`PartsSchedule`
`options`	`MergePartsOptions`

Returns

Promise<unknown>

mergeSurfaceAreaJobs()

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

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

Parameters

Parameter	Type
`schedule`	`AreaSchedule`
`options`	`Pick`<`AreaMergeOptions`, `"maxWorkers"` \| `"signal"` \| `"logger"`>

Returns

Promise<SurfaceColumns>

previewArea()

previewArea(polygon, options?): AreaPreview

Estimates an area run from its tile count; submits nothing. The cost uses a default price per job (previewAreaWithPricing uses the live price); for a facade run use previewAreaBatches. Throws when the polygon needs more non-empty tiles than the limit.

Parameters

Parameter	Type
`polygon`	`Polygon`
`options`	{ `analysisType?`: `string`; `maxTilesOverride?`: `number`; }
`options.analysisType?`	`string`
`options.maxTilesOverride?`	`number`

Returns

AreaPreview

Example

const preview = 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

Parameter	Type
`input`	`RunAreaInput`
`polygon`	`Polygon`
`options`	`RunAreaOptions`

Returns

Promise<AreaBatchPreview>

previewAreaWithPricing()

previewAreaWithPricing(polygon, options): Promise<AreaPreviewWithPricing>

Like previewArea, but priced with the API's current price for the analysis. When the price list cannot be fetched a warning is logged and the default price is used (pricingSource is "fallback").

Parameters

Parameter	Type
`polygon`	`unknown`
`options`	{ `analysisType`: `AnalysesName`; `forceRefresh?`: `boolean`; `maxTilesOverride?`: `number`; }
`options.analysisType`	`AnalysesName`
`options.forceRefresh?`	`boolean`
`options.maxTilesOverride?`	`number`

Returns

Promise<AreaPreviewWithPricing>

previewParts()

previewParts(input, options?): PartsPreview

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

Parameters

Parameter	Type
`input`	`Readonly`<`Record`<`string`, `unknown`>>
`options`	`PartsOptions`

Returns

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

Parameter	Type
`input`	`Readonly`<`Record`<`string`, `unknown`>>
`options`	`SubmitOptions`

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

Parameter	Type
`input`	`Readonly`<`Record`<`string`, `unknown`>>
`options`	`SubmitOptions` & `RunAndWaitOptions`

Returns

Promise<unknown>

Example

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

runArea()

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.

Parameters

Parameter	Type	Description
`input`	`RunAreaInput`	the analysis request, as for `runAndWait`, plus the area settings.
`polygon`	`Polygon`	the area to analyse.
`options`	`RunAreaOptions`	`maxWorkers` (requests in flight at once), `maxTilesOverride`, `retryFrom`, `onAccepted`, `signal` and `logger`.

Returns

Promise<AreaSchedule>

the saved AreaSchedule with one entry for each submitted tile.

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 });

runAreaAndWait()

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.

Parameters

Parameter	Type
`input`	`RunAreaInput`
`polygon`	`Polygon`
`options`	`RunAreaAndWaitOptions`

Returns

Promise<SurfaceColumns | AreaResult>

Throws

when the run does not finish within areaTimeout.

Throws

when areaTimeout is not a positive finite number.

Example

const result = await client.runAreaAndWait(input, polygon, { areaTimeout: 1800 });

runParts()

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

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

Parameters

Parameter	Type
`input`	`Readonly`<`Record`<`string`, `unknown`>>
`options`	`PartsOptions`

Returns

Promise<PartsSchedule>

InfraredClientConfig

Import from @infrared-city/infrared-sdk-ts.

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

Property	Modifier	Type	Description	Inherited from
`apiKey?`	`readonly`	`string`	API key, sent in the `X-Api-Key` header on every request.	`AuthOptions`.`apiKey`
`auth?`	`readonly`	`AuthResolver`	A custom function that supplies the request headers carrying the credentials. It cannot be combined with `apiKey`, `token` or `getToken`.	-
`baseUrl?`	`readonly`	`string` \| `URL`	The API base URL. Defaults to `INFRARED_BASE_URL`, then `https://api.infrared.city/v2`.	-
`bigPayloadThresholdBytes?`	`readonly`	`number`	Request archives larger than this many bytes are uploaded separately instead of being sent in the request. A non-negative whole number; default 5 MiB (5 242 880).	-
`downloadTimeout?`	`readonly`	`number`	Alias of `downloadTimeoutMs`, also in milliseconds; `downloadTimeoutMs` wins when both are given.	-
`downloadTimeoutMs?`	`readonly`	`number`	Timeout for each result download, in milliseconds. Default 600 000.	-
`env?`	`readonly`	`InfraredEnvBindings`	Environment values to use in place of `process.env`.	-
`fetch?`	`readonly`	{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	The `fetch` implementation to use for requests. Defaults to the global `fetch`.	-
`gatewayBaseUrl?`	`readonly`	`string` \| `URL`	The base URL that large request archives are uploaded through. Defaults to `baseUrl`.	-
`geometryUrlStore?`	`readonly`	`GeometryUrlStore`	Keeps the URLs of uploaded tile geometry outside this client, so a new client (a new worker, or the page after a reload) does not upload the same geometry again while its signed URL is still valid. Before an upload the SDK looks in its own memory, then calls `get` once per geometry; after an upload it calls `set`. The SDK makes the keys (they contain a digest of the credentials, never the credentials) and the `expiresAt` values (23 h after the upload, or the signed URL's end when earlier). When the server refuses a stored URL, the SDK uploads again and overwrites the entry. A `get` or `set` that throws or hangs gives one warning and an upload; the run does not fail. An entry is a read link to your geometry for its lifetime; treat the store like a cache of secrets. Default: no store, the URLs stay in this realm's memory only. Example `const client = new InfraredClient({ apiKey, geometryUrlStore: { get: (key) => JSON.parse(sessionStorage.getItem(`ir:${key}`) ?? "null") ?? undefined, set: (key, url, expiresAt) => sessionStorage.setItem(`ir:${key}`, JSON.stringify({ url, expiresAt })), }, });`	-
`getToken?`	`readonly`	() => `string` \| `Promise`<`string`>	Returns the bearer token, called before every request so a refreshed token is picked up. Must return a non-empty string.	`AuthOptions`.`getToken`
`logger?`	`readonly`	`Logger`	Where the SDK's warnings go. Defaults to `consoleLogger`; use `silentLogger` to silence them.	-
`onGeometryReuseProbe?`	`readonly`	`OnGeometryReuseProbe`	Called when the first submission that refers to previously uploaded geometry settles whether the API supports that. The event carries the `outcome` (`"supported"` or `"unsupported"`) and the ids of the jobs that were accepted.	-
`surface?`	`readonly`	`InfraredSurface`	The application the calls come from. Defaults to `"script"`.	`AuthOptions`.`surface`
`timeout?`	`readonly`	`number`	Alias of `timeoutMs`, also in milliseconds; `timeoutMs` wins when both are given.	-
`timeoutMs?`	`readonly`	`number`	Timeout for each API request, in milliseconds. Default 180 000.	-
`token?`	`readonly`	`string`	A fixed bearer token (JWT), sent in the `Authorization` header.	`AuthOptions`.`token`

InfraredClientOptions

Import from @infrared-city/infrared-sdk-ts.

InfraredClientOptions = InfraredClientConfig

Another name for InfraredClientConfig.

InfraredEnvBindings

Import from @infrared-city/infrared-sdk-ts.

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

Property	Modifier	Type	Description
`INFRARED_API_KEY?`	`readonly`	`string`	The API key, used when `apiKey` is not given.
`INFRARED_BASE_URL?`	`readonly`	`string`	The API base URL, used when `baseUrl` is not given.
`INFRARED_GEOMETRY_REF_ENABLED?`	`readonly`	`string`	Turns geometry reuse on or off. Accepts `1`, `true`, `yes` or `on` for on, and `0`, `false`, `no` or `off` for off (any letter case). Unset or empty means on; any other value makes the client constructor throw a `TypeError`.

InfraredSurface

Import from @infrared-city/infrared-sdk-ts.

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.

initializeCore

Import from @infrared-city/infrared-sdk-ts, @infrared-city/infrared-sdk-ts/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

Parameter	Type	Description
`options`	`InitializeCoreOptions`	Where to load the core from; see `InitializeCoreOptions`.

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.

InitializeCoreOptions

Import from @infrared-city/infrared-sdk-ts, @infrared-city/infrared-sdk-ts/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

Property	Modifier	Type	Description
`bytes?`	`readonly`	`BufferSource`	The bytes of the core WebAssembly file, when you have already loaded them.
`module?`	`readonly`	`Module`	An already compiled core WebAssembly module.
`threads?`	`readonly`	`number`	Node 22 or later only: run the core on this many threads, using the threaded core that ships in the package (loaded only when this is above 1). Omitted or `1` is the default single-threaded core. Results are identical to the single-threaded core, and facade merges are faster. It cannot be combined with `url`, `bytes` or `module`, and the browser and worker entry points refuse a value above 1. With the threaded core, a failure inside the core on any thread ends the Node process (killed with SIGKILL, which no handler can catch) after writing one JSON line to stderr. The same happens when the core runs out of WebAssembly memory near the 4 GiB limit. With the single-threaded core the same failure is a thrown error instead.
`url?`	`readonly`	`string` \| `URL`	URL to fetch the core WebAssembly file from.

JobsServiceOptions

Import from @infrared-city/infrared-sdk-ts.

Settings for constructing a JobsService.

Properties

Property	Modifier	Type	Description
`auth`	`readonly`	`AuthResolver`	Supplies the authentication headers for each request.
`backoffCapSeconds?`	`readonly`	`number`	Upper limit on the delay between status reads while waiting, in seconds.
`baseUrl`	`readonly`	`string` \| `URL`	Base URL of the Infrared API.
`bigPayloadThresholdBytes?`	`readonly`	`number`	Payload size in bytes above which a submission is uploaded and sent by reference instead of inline. Default 5 MiB.
`binaryUrlReuse?`	`readonly`	`boolean`	Reuse the links of binary content already uploaded instead of uploading it again. Default `true`.
`downloadTimeoutMs?`	`readonly`	`number`	Timeout for downloading a result archive, in milliseconds. Default 600000.
`fetch?`	`readonly`	{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	Custom `fetch` implementation.
`gatewayBaseUrl?`	`readonly`	`string` \| `URL`	Base URL used for large-payload uploads. Defaults to `baseUrl`.
`geometryReuseEnabled?`	`readonly`	`boolean`	Reuse geometry already accepted by the service instead of resending it. Default `true`.
`geometryUrlStore?`	`readonly`	`GeometryUrlStore`	Keeps uploaded geometry URLs for a new client. See `InfraredClientConfig.geometryUrlStore`.
`logger?`	`readonly`	`Logger`	Where the service writes its warnings.
`onGeometryReuseProbe?`	`readonly`	`OnGeometryReuseProbe`	Called when the first submission that references previously sent geometry settles, with the outcome (`supported` or `unsupported`).
`pollIntervalMs?`	`readonly`	`number`	Fixed delay between status reads while waiting, in milliseconds. By default the delay adapts.
`timeoutMs?`	`readonly`	`number`	Timeout for one API request, in milliseconds. Default 180000.

Logger

Import from @infrared-city/infrared-sdk-ts.

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

Properties

Property	Modifier	Type	Description
`debug`	`readonly`	(...`args`) => `void`	Log a debug message.
`error`	`readonly`	(...`args`) => `void`	Log an error.
`info`	`readonly`	(...`args`) => `void`	Log an informational message.
`warn`	`readonly`	(...`args`) => `void`	Log a warning.

OnGeometryReuseProbe

Import from @infrared-city/infrared-sdk-ts.

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

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

Parameters

Parameter	Type
`event`	`GeometryReuseProbeEvent`

Returns

void | Promise<void>

ServiceOptions

Import from @infrared-city/infrared-sdk-ts.

Options shared by the SDK's service classes.

Extended by

WeatherServiceOptions

Properties

Property	Modifier	Type	Description
`auth`	`readonly`	`AuthResolver`	Supplies the authentication headers for each request.
`baseUrl`	`readonly`	`string` \| `URL`	Base URL of the API the service calls.
`fetch?`	`readonly`	{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	A `fetch` implementation to use instead of the global one.
`logger?`	`readonly`	`Logger`	Where the service's own messages, such as warnings, go. `InfraredClient` passes its `logger` here, so choosing `silentLogger` silences the SDK's warnings, and a Node caller can capture them. A service created on its own defaults to `consoleLogger`.
`timeoutMs?`	`readonly`	`number`	Time limit for one request, in milliseconds.

silentLogger

Import from @infrared-city/infrared-sdk-ts.

const silentLogger: Logger

A Logger that discards every message.

VERSION

Import from @infrared-city/infrared-sdk-ts.

const VERSION: "1.0.0" = "1.0.0"

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