---
title: Client
source: https://infrared.city/docs/sdk/1.1/api/typescript/client/
---

# Client

<a id="authheaders"></a>

## AuthHeaders

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

> **AuthHeaders** = `Readonly`&lt;`Record`&lt;`string`, `string`&gt;&gt;

The HTTP headers that authenticate one request.

***

<a id="authoptions"></a>

## AuthOptions

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`](client.md#infraredclientconfig)

### Properties

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

***

<a id="authresolver"></a>

## AuthResolver

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

> **AuthResolver** = () => `Promise`&lt;[`AuthHeaders`](client.md#authheaders)&gt;

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

### Returns

`Promise`&lt;[`AuthHeaders`](client.md#authheaders)&gt;

***

<a id="buildauthresolver"></a>

## buildAuthResolver

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

> **buildAuthResolver**(`options`): [`AuthResolver`](client.md#authresolver)

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

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`AuthOptions`](client.md#authoptions) | The credentials to use; see [AuthOptions](client.md#authoptions). |

### Returns

[`AuthResolver`](client.md#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.

***

<a id="consolelogger"></a>

## consoleLogger

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

> `const` **consoleLogger**: [`Logger`](client.md#logger) = `console`

A `Logger` that writes to the global `console`.

***

<a id="coreversion"></a>

## coreVersion

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.

***

<a id="geometryreuseprobeevent"></a>

## GeometryReuseProbeEvent

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

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="geometryreuseprobeevent-acceptedjobids"></a> `acceptedJobIds` | `readonly` | readonly `string`\[\] | Ids of the jobs that were accepted by this submission. |
| <a id="geometryreuseprobeevent-outcome"></a> `outcome` | `readonly` | [`GeometryReuseProbeOutcome`](client.md#geometryreuseprobeoutcome) | Whether the API resolved the geometry reference. |

***

<a id="geometryreuseprobeoutcome"></a>

## GeometryReuseProbeOutcome

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.

***

<a id="geometryurlentry"></a>

## GeometryUrlEntry

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

One geometry URL that a [GeometryUrlStore](client.md#geometryurlstore) keeps.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="geometryurlentry-expiresat"></a> `expiresAt` | `readonly` | `number` | When the SDK stops using the URL, in milliseconds since the Unix epoch. |
| <a id="geometryurlentry-url"></a> `url` | `readonly` | `string` | The signed URL of the uploaded geometry. |

***

<a id="geometryurlstore"></a>

## GeometryUrlStore

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

<a id="geometryurlstore-claim"></a>

#### claim()?

> `optional` **claim**(`key`): `Promise`&lt;() => `void`&gt;

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

| Parameter | Type |
| ------ | ------ |
| `key` | `string` |

##### Returns

`Promise`&lt;() => `void`&gt;

##### Example

**Web Locks, in a page or a worker:**

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

***

<a id="geometryurlstore-get"></a>

#### get()

> **get**(`key`): [`GeometryUrlEntry`](client.md#geometryurlentry) \| `Promise`&lt;[`GeometryUrlEntry`](client.md#geometryurlentry) \| `undefined`&gt; \| `undefined`

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

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `key` | `string` |

##### Returns

[`GeometryUrlEntry`](client.md#geometryurlentry) \| `Promise`&lt;[`GeometryUrlEntry`](client.md#geometryurlentry) \| `undefined`&gt; \| `undefined`

***

<a id="geometryurlstore-set"></a>

#### set()

> **set**(`key`, `url`, `expiresAt`): `void` \| `Promise`&lt;`void`&gt;

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

##### Parameters

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

##### Returns

`void` \| `Promise`&lt;`void`&gt;

***

<a id="infraredclient"></a>

## InfraredClient

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

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`InfraredClientConfig`](client.md#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.

### Other

<a id="infraredclient-analyses"></a>

#### analyses

> `readonly` **analyses**: [`AnalysisService`](run-an-analysis.md#analysisservice)

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

***

<a id="infraredclient-apikey"></a>

#### apiKey

> `readonly` **apiKey**: `string` \| `undefined`

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

***

<a id="infraredclient-baseurl"></a>

#### baseUrl

> `readonly` **baseUrl**: `string`

The API base URL in use, without trailing slashes.

***

<a id="infraredclient-billing"></a>

#### billing

> `readonly` **billing**: [`BillingService`](billing.md#billingservice)

The public price list.

***

<a id="infraredclient-buildings"></a>

#### buildings

> `readonly` **buildings**: [`BuildingsService`](buildings.md#buildingsservice)

Buildings around a site.

***

<a id="infraredclient-groundmaterials"></a>

#### groundMaterials

> `readonly` **groundMaterials**: [`GroundMaterialsService`](ground-materials.md#groundmaterialsservice)

Ground materials around a site.

***

<a id="infraredclient-jobs"></a>

#### jobs

> `readonly` **jobs**: [`JobsService`](run-an-analysis.md#jobsservice)

Submits jobs, reads their status and downloads results.

***

<a id="infraredclient-logger"></a>

#### logger

> `readonly` **logger**: [`Logger`](client.md#logger)

Where the SDK's warnings go.

***

<a id="infraredclient-vegetation"></a>

#### vegetation

> `readonly` **vegetation**: [`VegetationService`](vegetation.md#vegetationservice)

Trees around a site.

***

<a id="infraredclient-weather"></a>

#### weather

> `readonly` **weather**: [`WeatherService`](weather.md#weatherservice)

Weather stations and data.

***

<a id="infraredclient-checkareastate"></a>

#### checkAreaState()

> **checkAreaState**(`schedule`, `options?`): `Promise`&lt;[`AreaState`](run-an-analysis.md#areastate)&gt;

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

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `schedule` | [`AreaSchedule`](run-an-analysis.md#areaschedule) |
| `options` | [`CheckAreaStateOptions`](run-an-analysis.md#checkareastateoptions) |

##### Returns

`Promise`&lt;[`AreaState`](run-an-analysis.md#areastate)&gt;

***

<a id="infraredclient-checkpartsstate"></a>

#### checkPartsState()

> **checkPartsState**(`schedule`, `options?`): `Promise`&lt;[`AreaState`](run-an-analysis.md#areastate)&gt;

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

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `schedule` | [`PartsSchedule`](run-an-analysis.md#partsschedule) |
| `options` | [`CheckAreaStateOptions`](run-an-analysis.md#checkareastateoptions) |

##### Returns

`Promise`&lt;[`AreaState`](run-an-analysis.md#areastate)&gt;

***

<a id="infraredclient-decompressresult"></a>

#### 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`

***

<a id="infraredclient-generatetiles"></a>

#### generateTiles()

> **generateTiles**(`polygon`, `options?`): [`Tile`](tiling.md#tile)\[\]\[\]

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

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `polygon` | [`Polygon`](tiling.md#polygon) |
| `options` | \{ `analysisType?`: `string`; `maxTilesOverride?`: `number`; \} |
| `options.analysisType?` | `string` |
| `options.maxTilesOverride?` | `number` |

##### Returns

[`Tile`](tiling.md#tile)\[\]\[\]

***

<a id="infraredclient-mergeareajobs"></a>

#### mergeAreaJobs()

> **mergeAreaJobs**(`schedule`, `options?`): `Promise`&lt;[`AreaResult`](results-and-legend.md#arearesult)&gt;

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`](run-an-analysis.md#areaschedule) |
| `options` | [`AreaMergeOptions`](run-an-analysis.md#areamergeoptions) |

##### Returns

`Promise`&lt;[`AreaResult`](results-and-legend.md#arearesult)&gt;

***

<a id="infraredclient-mergeparts"></a>

#### mergeParts()

> **mergeParts**(`schedule`, `options?`): `Promise`&lt;`unknown`&gt;

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

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `schedule` | [`PartsSchedule`](run-an-analysis.md#partsschedule) |
| `options` | [`MergePartsOptions`](run-an-analysis.md#mergepartsoptions) |

##### Returns

`Promise`&lt;`unknown`&gt;

***

<a id="infraredclient-mergesurfaceareajobs"></a>

#### mergeSurfaceAreaJobs()

> **mergeSurfaceAreaJobs**(`schedule`, `options?`): `Promise`&lt;[`SurfaceColumns`](results-and-legend.md#surfacecolumns)&gt;

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

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `schedule` | [`AreaSchedule`](run-an-analysis.md#areaschedule) |
| `options` | `Pick`&lt;[`AreaMergeOptions`](run-an-analysis.md#areamergeoptions), `"maxWorkers"` \| `"signal"` \| `"logger"`&gt; |

##### Returns

`Promise`&lt;[`SurfaceColumns`](results-and-legend.md#surfacecolumns)&gt;

***

<a id="infraredclient-previewarea"></a>

#### previewArea()

> **previewArea**(`polygon`, `options`): `Promise`&lt;[`AreaPreview`](run-an-analysis.md#areapreview)&gt;

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

| Parameter | Type |
| ------ | ------ |
| `polygon` | [`Polygon`](tiling.md#polygon) |
| `options` | \{ `analysisType`: `string`; `maxTilesOverride?`: `number`; \} |
| `options.analysisType` | `string` |
| `options.maxTilesOverride?` | `number` |

##### Returns

`Promise`&lt;[`AreaPreview`](run-an-analysis.md#areapreview)&gt;

##### Throws

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

##### Example

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

***

<a id="infraredclient-previewareabatches"></a>

#### previewAreaBatches()

> **previewAreaBatches**(`input`, `polygon`, `options?`): `Promise`&lt;[`AreaBatchPreview`](run-an-analysis.md#areabatchpreview)&gt;

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`](run-an-analysis.md#runareainput) |
| `polygon` | [`Polygon`](tiling.md#polygon) |
| `options` | [`RunAreaOptions`](run-an-analysis.md#runareaoptions) |

##### Returns

`Promise`&lt;[`AreaBatchPreview`](run-an-analysis.md#areabatchpreview)&gt;

***

<a id="infraredclient-previewareawithpricing"></a>

#### ~~previewAreaWithPricing()~~

> **previewAreaWithPricing**(`polygon`, `options`): `Promise`&lt;[`AreaPreviewWithPricing`](run-an-analysis.md#areapreviewwithpricing)&gt;

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `polygon` | `unknown` |
| `options` | \{ `analysisType`: [`AnalysesName`](requests.md#analysesname); `forceRefresh?`: `boolean`; `maxTilesOverride?`: `number`; \} |
| `options.analysisType` | [`AnalysesName`](requests.md#analysesname) |
| `options.forceRefresh?` | `boolean` |
| `options.maxTilesOverride?` | `number` |

##### Returns

`Promise`&lt;[`AreaPreviewWithPricing`](run-an-analysis.md#areapreviewwithpricing)&gt;

##### Deprecated

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

***

<a id="infraredclient-previewparts"></a>

#### previewParts()

> **previewParts**(`input`, `options?`): `Promise`&lt;[`PartsPreview`](run-an-analysis.md#partspreview)&gt;

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

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; |
| `options` | [`PartsOptions`](run-an-analysis.md#partsoptions) |

##### Returns

`Promise`&lt;[`PartsPreview`](run-an-analysis.md#partspreview)&gt;

***

<a id="infraredclient-run"></a>

#### run()

> **run**(`input`, `options?`): `Promise`&lt;[`Job`](run-an-analysis.md#job)&gt;

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`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; |
| `options` | [`SubmitOptions`](requests.md#submitoptions) |

##### Returns

`Promise`&lt;[`Job`](run-an-analysis.md#job)&gt;

##### Example

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

***

<a id="infraredclient-runandwait"></a>

#### runAndWait()

> **runAndWait**(`input`, `options?`): `Promise`&lt;`unknown`&gt;

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`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; |
| `options` | [`SubmitOptions`](requests.md#submitoptions) & [`RunAndWaitOptions`](run-an-analysis.md#runandwaitoptions) |

##### Returns

`Promise`&lt;`unknown`&gt;

##### Example

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

***

<a id="infraredclient-runarea"></a>

#### runArea()

##### Call Signature

> **runArea**(`input`, `polygon`, `options?`): `Promise`&lt;[`AreaSchedule`](run-an-analysis.md#areaschedule)&gt;

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

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `input` | [`RunAreaInput`](run-an-analysis.md#runareainput) | the analysis request, as for `runAndWait`, plus the area settings, or a list of them. |
| `polygon` | [`Polygon`](tiling.md#polygon) | the area to analyse. |
| `options?` | [`RunAreaOptions`](run-an-analysis.md#runareaoptions) | `maxTilesOverride`, `retryFrom`, `onAccepted`, `signal` and `logger`. |

###### Returns

`Promise`&lt;[`AreaSchedule`](run-an-analysis.md#areaschedule)&gt;

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

```ts
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`&lt;[`AreaSchedule`](run-an-analysis.md#areaschedule)\[\]&gt;

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

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `inputs` | readonly [`RunAreaInput`](run-an-analysis.md#runareainput)\[\] | - |
| `polygon` | [`Polygon`](tiling.md#polygon) | the area to analyse. |
| `options?` | [`RunAreaOptions`](run-an-analysis.md#runareaoptions) | `maxTilesOverride`, `retryFrom`, `onAccepted`, `signal` and `logger`. |

###### Returns

`Promise`&lt;[`AreaSchedule`](run-an-analysis.md#areaschedule)\[\]&gt;

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

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

***

<a id="infraredclient-runareaandwait"></a>

#### runAreaAndWait()

##### Call Signature

> **runAreaAndWait**(`input`, `polygon`, `options?`): `Promise`&lt;[`SurfaceColumns`](results-and-legend.md#surfacecolumns) \| [`AreaResult`](results-and-legend.md#arearesult)&gt;

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

| Parameter | Type |
| ------ | ------ |
| `input` | [`RunAreaInput`](run-an-analysis.md#runareainput) |
| `polygon` | [`Polygon`](tiling.md#polygon) |
| `options?` | [`RunAreaAndWaitOptions`](run-an-analysis.md#runareaandwaitoptions) |

###### Returns

`Promise`&lt;[`SurfaceColumns`](results-and-legend.md#surfacecolumns) \| [`AreaResult`](results-and-legend.md#arearesult)&gt;

###### 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

```ts
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`&lt;([`SurfaceColumns`](results-and-legend.md#surfacecolumns) \| [`AreaResult`](results-and-legend.md#arearesult))\[\]&gt;

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

| Parameter | Type |
| ------ | ------ |
| `inputs` | readonly [`RunAreaInput`](run-an-analysis.md#runareainput)\[\] |
| `polygon` | [`Polygon`](tiling.md#polygon) |
| `options?` | [`RunAreaAndWaitOptions`](run-an-analysis.md#runareaandwaitoptions) |

###### Returns

`Promise`&lt;([`SurfaceColumns`](results-and-legend.md#surfacecolumns) \| [`AreaResult`](results-and-legend.md#arearesult))\[\]&gt;

###### 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

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

***

<a id="infraredclient-runparts"></a>

#### runParts()

> **runParts**(`input`, `options?`): `Promise`&lt;[`PartsSchedule`](run-an-analysis.md#partsschedule)&gt;

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

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; |
| `options` | [`PartsOptions`](run-an-analysis.md#partsoptions) |

##### Returns

`Promise`&lt;[`PartsSchedule`](run-an-analysis.md#partsschedule)&gt;

### Run an analysis

<a id="infraredclient-runareastream"></a>

#### runAreaStream()

> **runAreaStream**(`inputs`, `polygon`, `options?`): `AsyncGenerator`&lt;[`AreaStreamItem`](run-an-analysis.md#areastreamitem), `void`, `undefined`&gt;

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

| Parameter | Type |
| ------ | ------ |
| `inputs` | [`RunAreaInput`](run-an-analysis.md#runareainput) \| readonly [`RunAreaInput`](run-an-analysis.md#runareainput)\[\] |
| `polygon` | [`Polygon`](tiling.md#polygon) |
| `options` | [`RunAreaAndWaitOptions`](run-an-analysis.md#runareaandwaitoptions) |

##### Returns

`AsyncGenerator`&lt;[`AreaStreamItem`](run-an-analysis.md#areastreamitem), `void`, `undefined`&gt;

##### Throws

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

##### Example

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

***

<a id="infraredclientconfig"></a>

## InfraredClientConfig

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`](client.md#authoptions)

### Properties

| Property | Modifier | Type | Description | Inherited from |
| ------ | ------ | ------ | ------ | ------ |
| <a id="infraredclientconfig-apikey"></a> `apiKey?` | `readonly` | `string` | API key, sent in the `X-Api-Key` header on every request. | [`AuthOptions`](client.md#authoptions).[`apiKey`](client.md#authoptions-apikey) |
| <a id="infraredclientconfig-auth"></a> `auth?` | `readonly` | [`AuthResolver`](client.md#authresolver) | A custom function that supplies the request headers carrying the credentials. It cannot be combined with `apiKey`, `token` or `getToken`. | - |
| <a id="infraredclientconfig-baseurl"></a> `baseUrl?` | `readonly` | `string` \| `URL` | The API base URL. Defaults to `INFRARED_BASE_URL`, then `https://api.infrared.city/v2`. | - |
| <a id="infraredclientconfig-batchsubmit"></a> `batchSubmit?` | `readonly` | `boolean` | Send the jobs of a binary area run in batch submits of up to 100 jobs when the API offers them: fewer requests, the same jobs. Each job keeps its own key and its own charge. Default `true` with `apiKey` or `token`; a client with `getToken` or `auth` sends one request per job, and so does `false`. | - |
| <a id="infraredclientconfig-bigpayloadthresholdbytes"></a> `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). | - |
| <a id="infraredclientconfig-downloadtimeout"></a> `downloadTimeout?` | `readonly` | `number` | Alias of `downloadTimeoutMs`, also in milliseconds; `downloadTimeoutMs` wins when both are given. | - |
| <a id="infraredclientconfig-downloadtimeoutms"></a> `downloadTimeoutMs?` | `readonly` | `number` | Timeout for each result download, in milliseconds. Default 600 000. | - |
| <a id="infraredclientconfig-env"></a> `env?` | `readonly` | [`InfraredEnvBindings`](client.md#infraredenvbindings) | Environment values to use in place of `process.env`. | - |
| <a id="infraredclientconfig-fetch"></a> `fetch?` | `readonly` | \{(`input`, `init?`): `Promise`&lt;`Response`&gt;; (`input`, `init?`): `Promise`&lt;`Response`&gt;; \} | The `fetch` implementation to use for requests. Defaults to the global `fetch`. | - |
| <a id="infraredclientconfig-gatewaybaseurl"></a> `gatewayBaseUrl?` | `readonly` | `string` \| `URL` | The base URL that large request archives are uploaded through. Defaults to `baseUrl`. | - |
| <a id="infraredclientconfig-geometryurlstore"></a> `geometryUrlStore?` | `readonly` | [`GeometryUrlStore`](client.md#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 })), }, });` | - |
| <a id="infraredclientconfig-gettoken"></a> `getToken?` | `readonly` | () => `string` \| `Promise`&lt;`string`&gt; | Returns the bearer token, called before every request so a refreshed token is picked up. Must return a non-empty string. | [`AuthOptions`](client.md#authoptions).[`getToken`](client.md#authoptions-gettoken) |
| <a id="infraredclientconfig-logger"></a> `logger?` | `readonly` | [`Logger`](client.md#logger) | Where the SDK's warnings go. Defaults to `consoleLogger`; use `silentLogger` to silence them. | - |
| <a id="infraredclientconfig-ongeometryreuseprobe"></a> `onGeometryReuseProbe?` | `readonly` | [`OnGeometryReuseProbe`](client.md#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. | - |
| <a id="infraredclientconfig-surface"></a> `surface?` | `readonly` | [`InfraredSurface`](client.md#infraredsurface) | The application the calls come from. Defaults to `"script"`. | [`AuthOptions`](client.md#authoptions).[`surface`](client.md#authoptions-surface) |
| <a id="infraredclientconfig-timeout"></a> `timeout?` | `readonly` | `number` | Alias of `timeoutMs`, also in milliseconds; `timeoutMs` wins when both are given. | - |
| <a id="infraredclientconfig-timeoutms"></a> `timeoutMs?` | `readonly` | `number` | Timeout for each API request, in milliseconds. Default 180 000. | - |
| <a id="infraredclientconfig-token"></a> `token?` | `readonly` | `string` | A fixed bearer token (JWT), sent in the `Authorization` header. | [`AuthOptions`](client.md#authoptions).[`token`](client.md#authoptions-token) |

***

<a id="infraredclientoptions"></a>

## InfraredClientOptions

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

> **InfraredClientOptions** = [`InfraredClientConfig`](client.md#infraredclientconfig)

Another name for `InfraredClientConfig`.

***

<a id="infraredenvbindings"></a>

## InfraredEnvBindings

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

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="infraredenvbindings-infrared_api_key"></a> `INFRARED_API_KEY?` | `readonly` | `string` | The API key, used when `apiKey` is not given. |
| <a id="infraredenvbindings-infrared_base_url"></a> `INFRARED_BASE_URL?` | `readonly` | `string` | The API base URL, used when `baseUrl` is not given. |
| <a id="infraredenvbindings-infrared_geometry_ref_enabled"></a> `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`. |

***

<a id="infraredsurface"></a>

## InfraredSurface

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](client.md#authoptions).

***

<a id="initializecore"></a>

## initializeCore

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

> **initializeCore**(`options?`): `Promise`&lt;`void`&gt;

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`](client.md#initializecoreoptions) | Where to load the core from; see `InitializeCoreOptions`. |

### Returns

`Promise`&lt;`void`&gt;

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.

***

<a id="initializecoreoptions"></a>

## InitializeCoreOptions

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

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="initializecoreoptions-bytes"></a> `bytes?` | `readonly` | `BufferSource` | The bytes of the core WebAssembly file, when you have already loaded them. |
| <a id="initializecoreoptions-module"></a> `module?` | `readonly` | `Module` | An already compiled core WebAssembly module. |
| <a id="initializecoreoptions-threads"></a> `threads?` | `readonly` | `number` | Node only: the number of core threads. Omitted: on Node 22 or later, `min(4, cores)` (8 from 16 cores) threads with the threaded core that ships in the package (one thread on Node 18 and 20, on one core, or when the pool does not start); `1`: the single-threaded core; above 1: that many threads (Node 22 or later). Results are identical for every count; the pool decodes and merges result tiles, zips request bodies and prepares the site. A count 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 core error on any thread is a thrown error. Running out of WebAssembly memory near the 4 GiB limit cannot be caught: it ends the Node process (SIGKILL) after writing one JSON line to stderr. |
| <a id="initializecoreoptions-url"></a> `url?` | `readonly` | `string` \| `URL` | URL to fetch the core WebAssembly file from. |

***

<a id="jobsserviceoptions"></a>

## JobsServiceOptions

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

Settings for constructing a `JobsService`.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="jobsserviceoptions-auth"></a> `auth` | `readonly` | [`AuthResolver`](client.md#authresolver) | Supplies the authentication headers for each request. |
| <a id="jobsserviceoptions-backoffcapseconds"></a> `backoffCapSeconds?` | `readonly` | `number` | Upper limit on the delay between status reads while waiting, in seconds. |
| <a id="jobsserviceoptions-baseurl"></a> `baseUrl` | `readonly` | `string` \| `URL` | Base URL of the Infrared API. |
| <a id="jobsserviceoptions-batchsubmit"></a> `batchSubmit?` | `readonly` | `boolean` | Send the jobs of a binary area run in batch submits (up to 100 jobs in one request) when the API offers them. Each job keeps its own key and its own charge. Default `true` with `apiKey` or `token`; a client with `getToken` or `auth` sends one request per job, and so does `false`. |
| <a id="jobsserviceoptions-bigpayloadthresholdbytes"></a> `bigPayloadThresholdBytes?` | `readonly` | `number` | Payload size in bytes above which a submission is uploaded and sent by reference instead of inline. Default 5 MiB. |
| <a id="jobsserviceoptions-binaryurlreuse"></a> `binaryUrlReuse?` | `readonly` | `boolean` | Reuse the links of binary content already uploaded instead of uploading it again. Default `true`. |
| <a id="jobsserviceoptions-downloadtimeoutms"></a> `downloadTimeoutMs?` | `readonly` | `number` | Timeout for downloading a result archive, in milliseconds. Default 600000. |
| <a id="jobsserviceoptions-fetch"></a> `fetch?` | `readonly` | \{(`input`, `init?`): `Promise`&lt;`Response`&gt;; (`input`, `init?`): `Promise`&lt;`Response`&gt;; \} | Custom `fetch` implementation. |
| <a id="jobsserviceoptions-gatewaybaseurl"></a> `gatewayBaseUrl?` | `readonly` | `string` \| `URL` | Base URL used for large-payload uploads. Defaults to `baseUrl`. |
| <a id="jobsserviceoptions-geometryreuseenabled"></a> `geometryReuseEnabled?` | `readonly` | `boolean` | Reuse geometry already accepted by the service instead of resending it. Default `true`. |
| <a id="jobsserviceoptions-geometryurlstore"></a> `geometryUrlStore?` | `readonly` | [`GeometryUrlStore`](client.md#geometryurlstore) | Keeps uploaded geometry URLs for a new client. See `InfraredClientConfig.geometryUrlStore`. |
| <a id="jobsserviceoptions-logger"></a> `logger?` | `readonly` | [`Logger`](client.md#logger) | Where the service writes its warnings. |
| <a id="jobsserviceoptions-ongeometryreuseprobe"></a> `onGeometryReuseProbe?` | `readonly` | [`OnGeometryReuseProbe`](client.md#ongeometryreuseprobe) | Called when the first submission that references previously sent geometry settles, with the outcome (`supported` or `unsupported`). |
| <a id="jobsserviceoptions-pollintervalms"></a> ~~`pollIntervalMs?`~~ | `readonly` | `number` | Fixed delay between status reads while waiting, in milliseconds. By default the delay adapts. **Deprecated** Removed in 2.0. The SDK sets the poll interval. |
| <a id="jobsserviceoptions-timeoutms"></a> `timeoutMs?` | `readonly` | `number` | Timeout for one API request, in milliseconds. Default 180000. |

***

<a id="logger"></a>

## Logger

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

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

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="logger-debug"></a> `debug` | `readonly` | (...`args`) => `void` | Log a debug message. |
| <a id="logger-error"></a> `error` | `readonly` | (...`args`) => `void` | Log an error. |
| <a id="logger-info"></a> `info` | `readonly` | (...`args`) => `void` | Log an informational message. |
| <a id="logger-warn"></a> `warn` | `readonly` | (...`args`) => `void` | Log a warning. |

***

<a id="ongeometryreuseprobe"></a>

## OnGeometryReuseProbe

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

> **OnGeometryReuseProbe** = (`event`) => `void` \| `Promise`&lt;`void`&gt;

A callback that receives a [GeometryReuseProbeEvent](client.md#geometryreuseprobeevent). It may return a promise.

### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`GeometryReuseProbeEvent`](client.md#geometryreuseprobeevent) |

### Returns

`void` \| `Promise`&lt;`void`&gt;

***

<a id="serviceoptions"></a>

## ServiceOptions

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

Options shared by the SDK's service classes.

### Extended by

- [`WeatherServiceOptions`](weather.md#weatherserviceoptions)

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="serviceoptions-auth"></a> `auth` | `readonly` | [`AuthResolver`](client.md#authresolver) | Supplies the authentication headers for each request. |
| <a id="serviceoptions-baseurl"></a> `baseUrl` | `readonly` | `string` \| `URL` | Base URL of the API the service calls. |
| <a id="serviceoptions-fetch"></a> `fetch?` | `readonly` | \{(`input`, `init?`): `Promise`&lt;`Response`&gt;; (`input`, `init?`): `Promise`&lt;`Response`&gt;; \} | A `fetch` implementation to use instead of the global one. |
| <a id="serviceoptions-logger"></a> `logger?` | `readonly` | [`Logger`](client.md#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`. |
| <a id="serviceoptions-timeoutms"></a> `timeoutMs?` | `readonly` | `number` | Time limit for one request, in milliseconds. |

***

<a id="silentlogger"></a>

## silentLogger

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

> `const` **silentLogger**: [`Logger`](client.md#logger)

A `Logger` that discards every message.

***

<a id="version"></a>

## VERSION

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"`.

***