Run an analysis, TypeScript SDK reference

AnalysisService

Import from @infrared-city/infrared-sdk.

Submits requests already written with the API's own keys; available as InfraredClient.analyses.

Constructors

Constructor

new AnalysisService(jobs): AnalysisService

Parameters

Parameter	Type	Description
`jobs`	`JobsService`	The jobs service that sends the request.

Returns

AnalysisService

Methods

execute()

execute(payload, options?): Promise<Job>

Submits a request that already uses the API's own keys; does not wait. Returns the accepted Job, or rejects with a TypeError when the payload is not an object or has no "analysis-type".

Parameters

Parameter	Type
`payload`	`WireAnalysisRequest`
`options`	`SubmitOptions`

Returns

Promise<Job>

AreaBatchPreview

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

The jobs, estimated time and estimated cost of an area run, from previewAreaBatches.

Properties

Property	Modifier	Type	Description
`estimatedCostTokens`	`readonly`	`number`	Estimated cost in tokens.
`estimatedTimeS`	`readonly`	`number`	Estimated run time in seconds.
`plannedJobCount`	`readonly`	`number`	The number of jobs the run would submit. Price from this, not `tileCount`, on a facade run.
`pricingSource`	`readonly`	`PricingSource`	Where the price came from: `"live"`, `"cached"` or `"stale"`.
`pricingVersion?`	`readonly`	`string`	The version of the price list used, when the list has one.
`sensorCount?`	`readonly`	`number`	Total sensors across the planned facade batches, or `undefined` for a grid preview.
`tileCount`	`readonly`	`number`	Non-empty tiles on the grid. Equal to `plannedJobCount` on a grid run.
`tokensPerJob`	`readonly`	`number`	The tokens charged for one job.

AreaJob

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

The job record of one tile inside an area schedule. The schedule's structure is fixed, but the job values are updated as polling proceeds.

Properties

Property	Modifier	Type	Description
`binary?`	`public`	`BinaryAcknowledgement`	The service's acknowledgement of a binary submission, when one was used.
`col`	`readonly`	`number`	Column of the tile in the tile grid.
`error?`	`public`	`string`	Why the job failed or was skipped, when it did.
`failureKind?`	`public`	`"send_refused"` \	`"host_refused"` \	`"rate_limited"` \	`"payment_required"` \	`"uncertain"` \	`"server_failed"` \	`"download_failed"` \	`"timeout"`	Why the tile has no result (see `TileFailureKind`).
`failureStatus?`	`public`	`number`	The HTTP status of the answer that decided `failureKind`, when there was one.
`invalidReference?`	`public`	`boolean`	True when this accepted reference cannot produce a trusted result.
`jobId?`	`public`	`string`	The job id assigned by the service, once the submission was accepted.
`lastJobSnapshot?`	`public`	`Job`	The most recent status the service reported for the job.
`result?`	`public`	`Record`<`string`, `unknown`>	The job's stored result, when one was kept.
`row`	`readonly`	`number`	Row of the tile in the tile grid.
`status`	`public`	`TileJobStatus`	Current state of the job.
`tileId`	`readonly`	`string`	Identifier of the tile this job covers.

AreaJobsService

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

AreaJobsService = Pick<JobsService, "prepareSubmission" \| "preflightPrepared" \| "submitPrepared" \| "getStatus"> & object

The job operations an area run needs: prepare, pre-check, submit and read the status of a job. InfraredClient.jobs satisfies it; a custom or mock service only has to provide the four required methods.

Type Declaration

Name	Type	Description
`binaryCapability()?`	(`signal?`) => `Promise`<`BinaryCapability`>	Reads the API's capability document, which decides whether a part of a daylight-factor run can use the binary route. Optional: without it the parts stay on the JSON route. A binary area run reads it once to check its route before the first paid POST.
`captures?`	`FacadeCaptures`	The client's cache of facade captures and layouts. Optional: without it nothing is captured.
`releasePreflight()?`	(`prepared`) => `void`	Frees what a pre-check is holding for tiles that are then not submitted. Optional: a service that retains nothing has nothing to free.

AreaMergeJobsService

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

AreaMergeJobsService = Pick<JobsService, "getStatus" \| "downloadResults"> & object

The jobs service mergeAreaJobs needs: it reads job status and downloads job results. InfraredClient.jobs satisfies it.

Type Declaration

Name	Type	Description
`captures?`	`FacadeCaptures`	The client's own facade capture and layout cache. Optional: when absent, no job inputs were captured and no cell triangles are synthesized.

AreaMergeOptions

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

Options for mergeAreaJobs.

Extended by

RunAreaAndWaitOptions

Properties

Property	Modifier	Type	Description
`block?`	`readonly`	`number`	Largest block, in cells per side, that the directional strategies process at once; at least 1. It trades speed against memory only: the result is the same for any value. Default 928.
`known?`	`readonly`	`Readonly`<`Record`<`string`, `TileJobStatus`>>	Job id to status, from your own earlier status checks. A job recorded as `"completed"` or `"failed"` is not asked about again, so a poll loop that ends with a merge sends no second round of status requests.
`logger?`	`readonly`	`Logger`	Logger that a tile dropped from the merge is warned through. `InfraredClient` passes its own.
~~`maxWorkers?`~~	`readonly`	`number`	Deprecated No effect: the engine sets the widths. Removed in 2.0.
`signal?`	`readonly`	`AbortSignal`	Aborts the merge when signalled.
`strategy?`	`readonly`	`"default"` \	`"directional"` \	`"directional_blend"`	How overlapping tiles are blended. Default `"default"`. `"directional"` and `"directional_blend"` apply to wind-speed analyses only and require `windDirectionDeg`.
`windDirectionDeg?`	`readonly`	`number`	Wind direction in degrees. Required for the directional strategies.

AreaPreview

Import from @infrared-city/infrared-sdk.

An estimate of an area run, from InfraredClient.previewArea, priced with the API price list: the planned jobs times the price of one job, and 10 seconds per job.

Properties

Property	Modifier	Type	Description
`estimatedCostTokens`	`readonly`	`number`	The estimated cost in tokens.
`estimatedTimeS`	`readonly`	`number`	A rough run time in seconds.
`pricingSource`	`readonly`	`PricingSource`	Where the price came from: `"live"`, `"cached"` (under 20 minutes old) or `"stale"` (the list could not be fetched again).
`pricingVersion?`	`readonly`	`string`	The version of the price list used, when the list has one.
`tileCount`	`readonly`	`number`	The number of non-empty tiles, each of which is one billed job.
`tokensPerJob`	`readonly`	`number`	The tokens charged for one job of the previewed analysis.

AreaPreviewWithPricing

Import from @infrared-city/infrared-sdk.

An AreaPreview priced with the API's price list, from InfraredClient.previewAreaWithPricing.

Deprecated

Use AreaPreview: InfraredClient.previewArea returns the same fields (tokensPerJob, pricingVersion) and a pricingSource of "live", "cached" or "stale". Removed in 2.0.

Extends

Omit<AreaPreview, "pricingSource">

Properties

Property	Modifier	Type	Description	Overrides	Inherited from
~~`estimatedCostTokens`~~	`readonly`	`number`	The estimated cost in tokens.	-	`AreaPreview`.`estimatedCostTokens`
~~`estimatedTimeS`~~	`readonly`	`number`	A rough run time in seconds.	-	`AreaPreview`.`estimatedTimeS`
~~`pricingSource`~~	`readonly`	`"remote"` \	`"fallback"`	`"remote"`: the price came from the API. `"fallback"` is never returned now: with no price list the call throws `PricingUnavailableError`.	-	-
~~`pricingVersion?`~~	`readonly`	`string`	The version of the price list used, when the list has one.	`AreaPreview`.`pricingVersion`	-
~~`tileCount`~~	`readonly`	`number`	The number of non-empty tiles, each of which is one billed job.	-	`AreaPreview`.`tileCount`
~~`tokensPerJob`~~	`readonly`	`number`	The tokens charged for one job of the previewed analysis.	`AreaPreview`.`tokensPerJob`	-

AreaSchedule

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

Everything needed to follow, merge or retry an area run: its jobs, polygon and the identity values that guard a retry. It can be saved with areaScheduleToJSON and restored with areaScheduleFromJSON. Job values stay mutable so polling can update them.

Properties

Property	Modifier	Type	Description
`analysisType`	`readonly`	`string`	The analysis type of the run.
`attempts?`	`readonly`	`Readonly`<`Record`<`string`, `number`>>	The attempt number of the current job or submission of each tile key. A missing key is attempt 1.
`batchingPolicyVersion?`	`readonly`	`number`	Version of the facade batching policy; set on facade runs.
`batchMembership?`	`readonly`	`Readonly`<`Record`<`string`, readonly `string`\[\]>>	The building ids in each facade batch, by batch key.
`batchSensorCounts?`	`readonly`	`Readonly`<`Record`<`string`, `number`>>	The number of sensors in each facade batch, by batch key.
`configHash`	`readonly`	`string`	Hash of the run's configuration. A retry must produce the same value.
`failedSubmissions`	`readonly`	readonly `string`\[\]	Ids of the tiles whose submission failed.
`geometryProbeJobIds?`	`readonly`	readonly `string`\[\]	Job ids of capability-probe jobs written by older SDK versions. This SDK submits none. A schedule saved by an older version still loads, but cannot be resumed.
`geometryProbeUncertain?`	`readonly`	`boolean`	Set by older SDK versions when a capability probe had an unknown outcome.
`gridShape`	`readonly`	readonly \[`number`, `number`\]	The tile grid size as `[rows, columns]`.
`invalidReferenceSubmissions?`	`readonly`	readonly `string`\[\]	Referenced jobs retained for billing and support, never polled or merged.
`jobs`	`readonly`	`ReadonlyMap`<`string`, `AreaJob`>	The job record of each tile, by tile id.
`maxSensorsPerJob?`	`readonly`	`number`	Maximum number of sensors in one job of a facade run.
`polygon`	`readonly`	`Polygon`	The polygon the run covers.
`runId?`	`readonly`	`string`	Identifier of the run, made once per schedule and kept across every `retryFrom`. Absent on a schedule written before this field existed; a retry of one then gets a fresh id.
`scheduleContractVersion?`	`readonly`	`number`	Version of the schedule record format, used to refuse a retry of a schedule that an older SDK wrote. Absent on a schedule written before the field existed.
`siteIdentity?`	`readonly`	`string`	Digest of the prepared site inputs; absent on older schedules or without SHA-256.
`submissionAbortStatus`	`readonly`	`number` \	`null`	The HTTP status that stopped submission early (for example 402), or `null` when submission was not aborted.
`surfaceFields?`	`readonly`	`boolean`	True for a facade or roof run.
`terrainContextMarginM?`	`readonly`	`number`	Margin of terrain context around each tile, in metres.
`tilePositions`	`readonly`	readonly `TilePosition`\[\]	The position of each tile in the grid.
`transport?`	`readonly`	`"json"` \	`"binary"`	How requests were sent: `"json"` or `"binary"`.
`uncertainSubmissions?`	`readonly`	readonly `string`\[\]	Entries whose POST may have been accepted. Never retry these automatically.
`weatherIdentity?`	`readonly`	`string`	Identity of the weather these tiles were computed against: the submitted weather columns, the location and the time window. Absent for an analysis that reads no weather. A retry compares it with the weather it would submit, so a resume cannot combine tiles computed against different weather into one grid. It is kept on the client and never sent.
`webhookEvents?`	`readonly`	readonly `string`\[\]	The job events that trigger `webhookUrl`.
`webhookUrl?`	`readonly`	`string`	The URL the API calls when a job reaches one of `webhookEvents`.
`wireVersion?`	`readonly`	`1`	Version of the binary wire format; present only with the binary transport.

areaScheduleFromJSON

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

areaScheduleFromJSON(value): AreaSchedule

Rebuilds a frozen schedule from the JSON saved by areaScheduleToJSON, validating it.

Parameters

Parameter	Type
`value`	`unknown`

Returns

AreaSchedule

Throws

when the JSON is not a valid area schedule.

AreaScheduleJSON

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

The JSON form of an AreaSchedule, as written by areaScheduleToJSON. Its fields match AreaSchedule, with jobs stored as an array of [tileId, job] pairs.

Properties

Property	Modifier	Type	Description
`analysisType`	`readonly`	`string`	See `AreaSchedule.analysisType`.
`attempts?`	`readonly`	`Readonly`<`Record`<`string`, `number`>>	See `AreaSchedule.attempts`.
`batchingPolicyVersion?`	`readonly`	`number`	See `AreaSchedule.batchingPolicyVersion`.
`batchMembership?`	`readonly`	`Readonly`<`Record`<`string`, readonly `string`\[\]>>	See `AreaSchedule.batchMembership`.
`batchSensorCounts?`	`readonly`	`Readonly`<`Record`<`string`, `number`>>	See `AreaSchedule.batchSensorCounts`.
`configHash`	`readonly`	`string`	See `AreaSchedule.configHash`.
`failedSubmissions`	`readonly`	readonly `string`\[\]	See `AreaSchedule.failedSubmissions`.
`geometryProbeJobIds?`	`readonly`	readonly `string`\[\]	See `AreaSchedule.geometryProbeJobIds`.
`geometryProbeUncertain?`	`readonly`	`boolean`	See `AreaSchedule.geometryProbeUncertain`.
`gridShape`	`readonly`	readonly \[`number`, `number`\]	See `AreaSchedule.gridShape`.
`invalidReferenceSubmissions?`	`readonly`	readonly `string`\[\]	See `AreaSchedule.invalidReferenceSubmissions`.
`jobs`	`readonly`	\`string`, [`AreaJob`\]\[\]	The job record of each tile, as `[tileId, job]` pairs.
`maxSensorsPerJob?`	`readonly`	`number`	See `AreaSchedule.maxSensorsPerJob`.
`polygon`	`readonly`	`Polygon`	See `AreaSchedule.polygon`.
`runId?`	`readonly`	`string`	See `AreaSchedule.runId`.
`scheduleContractVersion?`	`readonly`	`number`	See `AreaSchedule.scheduleContractVersion`.
`siteIdentity?`	`readonly`	`string`	See `AreaSchedule.siteIdentity`.
`submissionAbortStatus`	`readonly`	`number` \	`null`	See `AreaSchedule.submissionAbortStatus`.
`surfaceFields?`	`readonly`	`boolean`	See `AreaSchedule.surfaceFields`.
`terrainContextMarginM?`	`readonly`	`number`	See `AreaSchedule.terrainContextMarginM`.
`tilePositions`	`readonly`	readonly `TilePosition`\[\]	See `AreaSchedule.tilePositions`.
`transport?`	`readonly`	`"json"` \	`"binary"`	See `AreaSchedule.transport`.
`uncertainSubmissions?`	`readonly`	readonly `string`\[\]	See `AreaSchedule.uncertainSubmissions`.
`weatherIdentity?`	`readonly`	`string`	See `AreaSchedule.weatherIdentity`.
`webhookEvents?`	`readonly`	readonly `string`\[\]	See `AreaSchedule.webhookEvents`.
`webhookUrl?`	`readonly`	`string`	See `AreaSchedule.webhookUrl`.
`wireVersion?`	`readonly`	`1`	See `AreaSchedule.wireVersion`.

areaScheduleToJSON

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

areaScheduleToJSON(schedule): AreaScheduleJSON

Converts a schedule to plain JSON for saving; read it back with areaScheduleFromJSON.

Parameters

Parameter	Type
`schedule`	`AreaSchedule`

Returns

AreaScheduleJSON

AreaState

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

Progress of an area run: how many of its jobs are in each state.

Properties

Property	Modifier	Type	Description
`completedCount`	`readonly`	`number`	Jobs that completed.
`failedCount`	`readonly`	`number`	Jobs that failed.
`isComplete`	`readonly`	`boolean`	True when no job is pending or running.
`pendingCount`	`readonly`	`number`	Jobs not yet running.
`runningCount`	`readonly`	`number`	Jobs currently running.
`skippedCount`	`readonly`	`number`	Jobs that were skipped or are no longer polled.
`totalCount`	`readonly`	`number`	Total number of jobs.

AreaStatusService

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

AreaStatusService = Pick<JobsService, "getStatus"> & object

The status operations checkAreaState and runAreaAndWait need. InfraredClient.jobs satisfies it.

Type Declaration

Name	Type	Description
`batchedStatusSupported?`	`boolean`	Whether a status sweep costs a fixed couple of requests, not one per job. `runAreaAndWait` uses it to choose its poll interval.
`captures?`	`Pick`<`FacadeCaptures`, `"forget"` \	`"forgetSchedule"`>	The client's facade capture cache. Optional: the run releases the captures of a job that failed and of a run that fails or is aborted.
`getStatusBatch?`	`JobsService`\[`"getStatusBatch"`\]	Reads the status of many jobs in one request. Optional: without it each job is read on its own.

AreaStreamItem

Import from @infrared-city/infrared-sdk.

AreaStreamItem = \{ analysisType: string; error?: undefined; index: number; result: AreaResult \| SurfaceColumns; \} \| \{ analysisType: string; error: Error; index: number; result?: undefined; \}

One finished analysis of runAreaStream: its result, or the error that stopped it. The other analyses of the stream continue either way.

Union Members

Type Literal

\{ analysisType: string; error?: undefined; index: number; result: AreaResult \| SurfaceColumns; \}

Name	Type	Description
`analysisType`	`string`	-
`error?`	`undefined`	-
`index`	`number`	Index of the analysis in the `inputs` list.
`result`	`AreaResult` \	`SurfaceColumns`	-

Type Literal

\{ analysisType: string; error: Error; index: number; result?: undefined; \}

Name	Type	Description
`analysisType`	`string`	-
`error`	`Error`	Why this analysis gave no result, for example an `AreaTimeoutError` or the abort reason.
`index`	`number`	-
`result?`	`undefined`	-

AreaSubmissionPlan

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

The plan for one area run: the tiles, the requests built for them and the identity used to resume the run. submitAreaPlan sends it.

Properties

Property	Modifier	Type	Description
`analysisType`	`readonly`	`string`	The analysis the run performs.
`batchingPolicyVersion?`	`readonly`	`2`	-
`batchMembership?`	`readonly`	`Readonly`<`Record`<`string`, readonly `string`\[\]>>	-
`batchSensorCounts?`	`readonly`	`Readonly`<`Record`<`string`, `number`>>	-
`configHash`	`readonly`	`string`	Digest of the settings the plan was built with.
`entries`	`readonly`	readonly `SubmissionEntry`\[\]	The requests to send, one per job.
`gridShape`	`readonly`	readonly \[`number`, `number`\]	Rows and columns of the tile grid.
`localCellTris?`	`readonly`	`boolean`	Whether the caller asked for `cell-tris`, which the merge then builds locally. Every surface run keeps its layout capture for the outline; this flag only asks for the triangles.
`plannedJobCount?`	`readonly`	`number`	The number of jobs the run will submit. It equals the tile count on a grid run but can be larger on a facade run, where a tile can split into several separately billed jobs. When absent, use `entries.length`.
`polygon`	`readonly`	`Polygon`	The area the run covers.
`retryContext?`	`readonly`	`AreaRetryContext`	Present only when the run continues an earlier one with `retryFrom`.
`runId`	`readonly`	`string`	Identifies the run; each job's idempotency key is derived from it, and the schedule keeps it.
`siteIdentity?`	`readonly`	`string`	Digest of the site inputs; a resumed run checks it before it resubmits paid jobs.
`surfaceFields`	`readonly`	`boolean`	Whether the analysis returns per-surface fields rather than a grid.
`terrainContextMarginM`	`readonly`	`number`	-
`tilePositions`	`readonly`	readonly `TilePosition`\[\]	Where each tile sits in the grid.
`weatherIdentity?`	`readonly`	`string`	The weather this plan's payloads were built from, if it is provable.

checkAreaState

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

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

Poll every open job of a schedule once and return the resulting progress.

Each open job is asked once: in batches of up to 50 jobs where the service supports it, and per job otherwise. Each job record is updated in place. A job whose status request failed keeps its last status; the next check asks it again.

Parameters

Parameter	Type	Description
`service`	`AreaStatusService`	Reads job status, for example `client.jobs`.
`schedule`	`Pick`<`AreaSchedule`, `"jobs"`>	The schedule to poll. Only its `jobs` are read.
`options`	`CheckAreaStateOptions`	Concurrency, cancellation and a progress callback.

Returns

Promise<AreaState>

The counts of completed, failed, skipped, pending and running jobs.

Throws

when options.signal is aborted; the abort reason is thrown.

CheckAreaStateOptions

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

Options for checkAreaState.

Properties

Property	Modifier	Type	Description
~~`maxWorkers?`~~	`readonly`	`number`	Deprecated No effect: the engine sets the widths. Removed in 2.0.
`onProgress?`	`readonly`	(`state`) => `void`	Called with the run's counts once the check has read every job.
`signal?`	`readonly`	`AbortSignal`	Aborts the status check.

computeAreaState

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

computeAreaState(schedule): AreaState

Counts the jobs of a schedule by status; isComplete is true when none is pending or running.

Parameters

Parameter	Type
`schedule`	`Pick`<`AreaSchedule`, `"jobs"`>

Returns

AreaState

freePreparedSites

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

freePreparedSites(): number

Release every prepared site this realm holds; returns how many it held.

A long-lived process that has finished with a site can drop tens of megabytes here instead of waiting for the byte bound to evict them. The next runArea on that site prepares it again.

Returns

number

The number of sites that were held.

freezeAreaSchedule

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

freezeAreaSchedule(schedule): AreaSchedule

Returns a frozen copy of a schedule; its lists, polygon and job map cannot be changed.

Parameters

Parameter	Type
`schedule`	`AreaSchedule`

Returns

AreaSchedule

Job

Import from @infrared-city/infrared-sdk.

A submitted analysis job, as reported by the service.

Properties

Property	Modifier	Type	Description
`binary?`	`readonly`	`BinaryAcknowledgement`	The service's acknowledgement, when the job was submitted over the binary transport.
`error?`	`readonly`	`string`	The failure message, when the job failed.
`finishedAt?`	`readonly`	`string`	When the job finished, when reported.
`jobId`	`readonly`	`string`	The job's unique id.
`modelName`	`readonly`	`string`	The analysis the job runs; an empty string when the service did not report it.
`requestedAt`	`readonly`	`string`	When the job was requested, as reported by the service; empty when not reported.
`resultsUrl?`	`readonly`	`string`	Link to download the results from, when the service reports one.
`startedAt?`	`readonly`	`string`	When the job started running, when reported.
`status`	`readonly`	`JobStatus`	Current status of the job.

JobsService

Import from @infrared-city/infrared-sdk.

Submits analysis jobs, reads their status and downloads their results; available as InfraredClient.jobs.

Constructors

Constructor

new JobsService(options): JobsService

Parameters

Parameter	Type	Description
`options`	`JobsServiceOptions`	Base URL, credentials and transport settings.

Returns

JobsService

Throws

when no fetch is available or bigPayloadThresholdBytes is invalid.

Properties

batchSubmit

readonly batchSubmit: boolean

Area runs send their binary jobs in batch submits when the API offers them (JobsServiceOptions.batchSubmit).

captures

readonly captures: FacadeCaptures

This client's facade captures, in one capture store. They live only as long as the client: nothing is written to disk and nothing is saved in an AreaSchedule. The client has no dispose: call captures.free() when you are done with it.

Accessors

batchedStatusSupported

Get Signature

get batchedStatusSupported(): boolean

Whether the API's route for reading many job statuses at once has answered this client. false until it has, and for good once the API shows it lacks the route.

Returns

boolean

Methods

binaryCapability()

binaryCapability(signal?): Promise<BinaryCapability>

The API's live capability document, which says whether a model's binary route is available. It is cached for a short time, so repeated calls are cheap.

Parameters

Parameter	Type
`signal?`	`AbortSignal`

Returns

Promise<BinaryCapability>

decompress()

decompress(content, options?): ParsedResult

Unpacks a downloaded result archive and returns the parsed result.

Parameters

Parameter	Type
`content`	`Uint8Array`
`options?`	`ParseResultOptions`

Returns

ParsedResult

downloadResults()

downloadResults(jobId, options?): Promise<DownloadResult>

Downloads the result archive of a finished job, retrying a failed download a few times (each try with a fresh link). Pass options.job to skip reading the status.

Parameters

Parameter	Type
`jobId`	`string`
`options`	`DownloadResultsOptions`

Returns

Promise<DownloadResult>

Throws

when the job has not succeeded.

Throws

when options.job is a different job.

getStatus()

getStatus(jobId, options?): Promise<Job>

Reads one job's status.

Parameters

Parameter	Type
`jobId`	`string`
`options`	\{ `signal?`: `AbortSignal`; \}
`options.signal?`	`AbortSignal`

Returns

Promise<Job>

getStatusBatch()

getStatusBatch(jobIds, options?): Promise<StatusSweep>

Reads many job statuses at once, 50 ids per request. Ids it could not settle come back in unanswered for you to ask about one by one; it does not throw because of an API problem. An API without the route is asked once and never again.

Parameters

Parameter	Type
`jobIds`	readonly `string`\[\]
`options`	\{ `maxWorkers?`: `number`; `signal?`: `AbortSignal`; \}
`options.maxWorkers?`	`number`
`options.signal?`	`AbortSignal`

Returns

Promise<StatusSweep>

preflightPrepared()

preflightPrepared(prepared, options?): Promise<void>

Finishes all validation and encoding of a binary submission before any paid request is sent. The encoded bytes are kept (within a memory budget) and submitPrepared sends exactly those bytes. If you pre-check a whole plan and then do not submit part of it, call releasePreflight for the rest.

Parameters

Parameter	Type
`prepared`	`PreparedSubmission`
`options`	\{ `retain?`: `boolean`; `signal?`: `AbortSignal`; \}
`options.retain?`	`boolean`
`options.signal?`	`AbortSignal`

Returns

Promise<void>

prepareSubmission()

prepareSubmission(analysisType, payload, options?): PreparedSubmission

Validates and encodes a request without sending it; returns the PreparedSubmission.

Parameters

Parameter	Type
`analysisType`	`string`
`payload`	`Readonly`<`Record`<`string`, `unknown`>>
`options`	`Omit`<`SubmitOptions`, `"signal"`>

Returns

PreparedSubmission

releasePreflight()

releasePreflight(prepared): void

Frees what preflightPrepared is holding for a submission that will not happen.

Parameters

Parameter	Type
`prepared`	`PreparedSubmission`

Returns

void

submit()

submit(analysisType, payload, options?): Promise<Job>

Prepares and sends one analysis request; returns the accepted Job without waiting for it. The request is sent as binary unless options.transport is "json" or the analysis has no binary route.

Parameters

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

Returns

Promise<Job>

submitPrepared()

submitPrepared(prepared, options?): Promise<Job>

Sends a PreparedSubmission and returns the accepted Job; the options are used by area runs.

Parameters

Parameter	Type
`prepared`	`PreparedSubmission`
`options`	`SubmitPreparedOptions`

Returns

Promise<Job>

waitForCompletion()

waitForCompletion(jobId, options?): Promise<Job>

Waits for a job to succeed or fail: one GET /async/jobs/{id} 1 s after the call, then every 1 s until 10 s, then every 2 s. After HTTP 429, a 5xx or a network error it backs off (at most 30 s, never shorter than Retry-After). options.timeout is in seconds (default 900).

Parameters

Parameter	Type
`jobId`	`string`
`options`	`WaitForCompletionOptions`

Returns

Promise<Job>

The finished Job.

Throws

when the job fails.

Throws

when the timeout passes first.

Throws

when options.signal aborts the wait.

Throws

when a status request is refused for good (for example 401 or 404).

JobStatus

Import from @infrared-city/infrared-sdk.

JobStatus = typeof JobStatus\keyof typeof [JobStatus\]

One of the JobStatus values: "pending", "running", "succeeded", "failed" or "unknown".

const JobStatus: object

The states a job can be in: pending, running, succeeded, failed, or unknown when the service reports a status the SDK does not recognise.

Type Declaration

Name	Type	Default value
`Failed`	`"failed"`	`"failed"`
`Pending`	`"pending"`	`"pending"`
`Running`	`"running"`	`"running"`
`Succeeded`	`"succeeded"`	`"succeeded"`
`Unknown`	`"unknown"`	`"unknown"`

KernelPart

Import from @infrared-city/infrared-sdk.

One part of a parts plan: a job that covers some of the request's floors.

Properties

Property	Modifier	Type	Description
`floor_keys`	`readonly`	readonly `string`\[\]	Keys of the floors the part covers.
`floors`	`readonly`	readonly `unknown`\[\] \	`null`	The part's `floors` selectors; `null` for a request sent as one part.
`key`	`readonly`	`string`	Key of the part, unique within the plan.
`sensors`	`readonly`	`number`	Number of sensors in the part.

KernelPartsPlan

Import from @infrared-city/infrared-sdk.

The plan that splits a daylight-factor request into parts, parsed.

Properties

Property	Modifier	Type	Description
`notes`	`readonly`	readonly `string`\[\]	Notes on inputs the analysis accepts silently.
`parts`	`readonly`	readonly `KernelPart`\[\]	The parts, in plan order.
`target`	`readonly`	`number`	The target the plan was made for.
`tier`	`readonly`	`string`	The request tier the plan was made for, for example `"floors"` or `"buildings"`.
`total_sensors`	`readonly`	`number`	Sensors of the whole request.
`unsplit_reason`	`readonly`	`string` \	`null`	Why the request was sent as one part, when it was; otherwise `null`.

mergeAreaJobs

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

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

Poll a grid schedule once, download the results of its completed tiles and merge them into one grid.

Calling it again after a failure asks every unfinished job again.

Parameters

Parameter	Type	Description
`jobsService`	`AreaMergeJobsService`	Reads job status and downloads results, for example `client.jobs`.
`schedule`	`AreaSchedule`	The schedule returned by `runArea`.
`options`	`AreaMergeOptions`	Blend strategy, concurrency, cancellation and logging.

Returns

Promise<AreaResult>

The merged grid with its shape, legend range and any failed or skipped tiles.

Throws

when the schedule is a facade or surface schedule, contains an uncertain or invalid geometry reference, or options ask for a directional strategy on a non-wind analysis or without windDirectionDeg.

Throws

when any tile failed, was skipped or could not be downloaded.

MergePartsOptions

Import from @infrared-city/infrared-sdk.

Options for joining the results of a parts run.

Properties

Property	Modifier	Type	Description
`logger?`	`readonly`	`Logger`	Where a JSON fallback of the join is logged.
~~`maxWorkers?`~~	`readonly`	`number`	Deprecated No effect: the engine sets the widths. Removed in 2.0.
`resultFormat?`	`readonly`	`DaylightResultFormat`	As `PartsOptions.resultFormat`. Unset: `DEFAULT_DAYLIGHT_RESULT_FORMAT`.
`signal?`	`readonly`	`AbortSignal`	Aborts the polling and the downloads.

mergeSurfaceAreaJobs

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

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

Polls a surface schedule once, downloads the results of all its jobs and joins them into one set of surface columns.

Every job must have completed: any failed or missing submission, or any job still pending or running, makes the merge fail instead of returning a partial result. Calling it again after a failure asks every unfinished job again. A schedule with no jobs gives empty columns.

Parameters

Parameter	Type	Description
`jobsService`	`AreaMergeJobsService`	Reads job status and downloads results, for example `client.jobs`.
`schedule`	`AreaSchedule`	The schedule returned by `runArea` for a surface analysis.
`options`	`Pick`<`AreaMergeOptions`, `"maxWorkers"` \	`"signal"` \	`"logger"` \	`"known"`>	`signal` (cancellation) and `logger`; `maxWorkers` is deprecated (no effect).

Returns

Promise<SurfaceColumns>

The merged surface columns.

Throws

when the schedule is not a surface schedule, contains an uncertain or invalid geometry reference, has failed or uncertain submissions, has jobs that did not succeed, or a download or decode failed (the cause is attached).

Throws

when options.signal is aborted: the abort reason.

PartsOptions

Import from @infrared-city/infrared-sdk.

Options for submitting a request as parts.

Extended by

PartsWaitOptions

Properties

Property	Modifier	Type	Description
`maxParts?`	`readonly`	`number`	The most jobs the run may submit. `1` turns splitting off: the request is sent as one job, exactly as `analyses.execute` sends it. A plan with more parts than a larger value is refused before any request. Default: no limit.
~~`maxWorkers?`~~	`readonly`	`number`	Deprecated No effect: the engine sets the widths. Removed in 2.0.
`onAccepted?`	`readonly`	(`jobId`, `partKey`) => `void`	Called with the job id and part key of each part the server accepts. An observer only: use it to store job ids before the run returns.
`onProgress?`	`readonly`	(`state`) => `void`	Called with the progress of the run each time the parts are polled.
`resultFormat?`	`readonly`	`DaylightResultFormat`	The format of a daylight-factor result. `"irbf"`: a `DaylightFactorResult` (typed-array views, with `toJson()` on demand); parts ask the server for binary results when it offers them, else JSON, which is converted into the same frame. `"json"`: the JSON value. Unset: `DEFAULT_DAYLIGHT_RESULT_FORMAT`. Other analyses ignore it.
`retryFrom?`	`readonly`	`PartsSchedule`	A schedule from an earlier run of the same request (its `requestDigest` must match). Only the parts that failed (a failed submission or a failed job) are sent again; a part whose submission outcome is unknown never is.
`signal?`	`readonly`	`AbortSignal`	Aborts the run.
`transport?`	`readonly`	`"json"` \	`"binary"`	How the parts are sent, as for `analyses.execute`. Unset (the default) picks the route automatically from what the server supports: the binary route, where the scene is uploaded once, or JSON. `"json"` keeps every part on JSON; `"binary"` sends the request as a single job and never splits it.
`webhookEvents?`	`readonly`	readonly `string`\[\]	The job events that trigger `webhookUrl`.
`webhookUrl?`	`readonly`	`string`	A URL the API calls when a job reaches one of `webhookEvents`.

PartsPreview

Import from @infrared-city/infrared-sdk.

The offline answer of previewParts: what a run would submit and bill.

Properties

Property	Modifier	Type	Description
`analysisType`	`readonly`	`string`	The analysis type of the request.
`estimatedCostTokens`	`readonly`	`number`	Estimated cost of the run in tokens: `partCount` times `tokensPerJob`.
`notes`	`readonly`	readonly `string`\[\]	Notes on inputs the analysis accepts silently.
`partCount`	`readonly`	`number`	Jobs the run submits: 1 when the request does not split.
`parts`	`readonly`	readonly `object`\[\]	The parts of the plan; empty when the request is not planned into parts.
`pricingSource`	`readonly`	`PricingSource`	Where the price came from: `"live"`, `"cached"` or `"stale"`.
`pricingVersion?`	`readonly`	`string`	The version of the price list used, when the list has one.
`tokensPerJob`	`readonly`	`number`	Tokens billed per job.
`totalSensors`	`readonly`	`number`	Exact sensors of the request (the worker's own grid); 0 when not planned.
`unsplitReason?`	`readonly`	`string`	Why the request is sent as one part, when it is.

PartsSchedule

Import from @infrared-city/infrared-sdk.

A submitted parts run.

Like an AreaSchedule, its job records are updated in place while the run is polled. Keep it to merge the run later or to retry the failed parts.

Properties

Property	Modifier	Type	Description
`analysisType`	`readonly`	`string`	The analysis type of the run.
`failedSubmissions`	`readonly`	readonly `string`\[\]	Parts whose submission failed.
`jobs`	`readonly`	`ReadonlyMap`<`string`, `AreaJob`>	The job of each part, by part key.
`partKeys`	`readonly`	readonly `string`\[\]	Part keys, in plan order.
`plan`	`readonly`	`string`	The plan of the run, as text. Merging reads it.
`requestDigest?`	`readonly`	`string`	`sha256:` digest of the request's JSON bytes; a `retryFrom` must match it. Absent when the runtime has no SHA-256; such a schedule cannot be retried.
`resultFormat?`	`readonly`	`DaylightResultFormat`	The daylight-factor result format the run chose. `mergeParts` uses it when the caller names none. Absent on an older schedule.
`submissionAbortStatus`	`readonly`	`number` \	`null`	HTTP status that stopped the submission early, or `null` when it was not stopped.
`uncertainSubmissions`	`readonly`	readonly `string`\[\]	Parts whose submission may have been accepted. Never resubmitted automatically.

PartsWaitOptions

Import from @infrared-city/infrared-sdk.

Options for running parts and waiting for them to finish.

Extends

PartsOptions

Extended by

RunAndWaitOptions

Properties

Property	Modifier	Type	Description	Inherited from
`maxParts?`	`readonly`	`number`	The most jobs the run may submit. `1` turns splitting off: the request is sent as one job, exactly as `analyses.execute` sends it. A plan with more parts than a larger value is refused before any request. Default: no limit.	`PartsOptions`.`maxParts`
~~`maxWorkers?`~~	`readonly`	`number`	Deprecated No effect: the engine sets the widths. Removed in 2.0.	`PartsOptions`.`maxWorkers`
`onAccepted?`	`readonly`	(`jobId`, `partKey`) => `void`	Called with the job id and part key of each part the server accepts. An observer only: use it to store job ids before the run returns.	`PartsOptions`.`onAccepted`
`onProgress?`	`readonly`	(`state`) => `void`	Called with the progress of the run each time the parts are polled.	`PartsOptions`.`onProgress`
`resultFormat?`	`readonly`	`DaylightResultFormat`	The format of a daylight-factor result. `"irbf"`: a `DaylightFactorResult` (typed-array views, with `toJson()` on demand); parts ask the server for binary results when it offers them, else JSON, which is converted into the same frame. `"json"`: the JSON value. Unset: `DEFAULT_DAYLIGHT_RESULT_FORMAT`. Other analyses ignore it.	`PartsOptions`.`resultFormat`
`retryFrom?`	`readonly`	`PartsSchedule`	A schedule from an earlier run of the same request (its `requestDigest` must match). Only the parts that failed (a failed submission or a failed job) are sent again; a part whose submission outcome is unknown never is.	`PartsOptions`.`retryFrom`
`signal?`	`readonly`	`AbortSignal`	Aborts the run.	`PartsOptions`.`signal`
`timeout?`	`readonly`	`number`	Seconds to wait for every part. Default 900, the same as for one job. Checked before any request is sent.	-
`transport?`	`readonly`	`"json"` \	`"binary"`	How the parts are sent, as for `analyses.execute`. Unset (the default) picks the route automatically from what the server supports: the binary route, where the scene is uploaded once, or JSON. `"json"` keeps every part on JSON; `"binary"` sends the request as a single job and never splits it.	`PartsOptions`.`transport`
`webhookEvents?`	`readonly`	readonly `string`\[\]	The job events that trigger `webhookUrl`.	`PartsOptions`.`webhookEvents`
`webhookUrl?`	`readonly`	`string`	A URL the API calls when a job reaches one of `webhookEvents`.	`PartsOptions`.`webhookUrl`

prepareAnalysisPayload

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

prepareAnalysisPayload(input): Record<string, unknown>

Turns an analysis input into the request body for one analysis, with wire field names. Entity and metadata maps pass through unchanged.

Parameters

Parameter	Type	Description
`input`	`Readonly`<`Record`<`string`, `unknown`>>	The analysis input, with `analysisType` (or the wire key `analysis-type`).

Returns

Record<string, unknown>

The request body.

Throws

when the input is invalid for its analysis type.

prepareAreaPayload

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

const prepareAreaPayload: (input) => Record<string, unknown> = prepareAnalysisPayload

Alias of prepareAnalysisPayload.

Turns an analysis input into the request body for one analysis, with wire field names. Entity and metadata maps pass through unchanged.

Parameters

Parameter	Type	Description
`input`	`Readonly`<`Record`<`string`, `unknown`>>	The analysis input, with `analysisType` (or the wire key `analysis-type`).

Returns

Record<string, unknown>

The request body.

Throws

when the input is invalid for its analysis type.

PreparedSubmission

Import from @infrared-city/infrared-sdk.

A validated, mesh-packed request body that is ready to be submitted.

Properties

Property	Modifier	Type	Description
`analysisType`	`readonly`	`string`	The analysis the body is for, e.g. `"wind-speed"`.
`artifact?`	`readonly`	(`limits`) => `UploadArtifact` \	`Promise`<`UploadArtifact`>	Builds the tile's binary upload, for a body that an area plan produced. A direct submission has none.
`body`	`readonly`	`Readonly`<`Record`<`string`, `unknown`>>	The request body that will be sent.
`interiorBinary?`	`readonly`	`PreparedBinary`	A prepared binary upload for one part of an interior (daylight-factor) analysis. Absent on every other submission.
`interiorResultFormat?`	`readonly`	`"json"` \	`"irbf"`	The result format an interior binary part asks for; unset means `"json"`.
`json?`	`readonly`	() => `Uint8Array`	The exact JSON bytes of `body`, when they were already written once. The JSON route sends these bytes instead of serializing `body` again. A direct submission has none.
`reuseScope?`	`readonly`	`string`	Scope under which compatible geometry from earlier submissions can be reused.
`transport`	`readonly`	`"json"` \	`"binary"`	How the body is sent: as JSON or as a compact binary upload.

preparedWeatherIdentity

Import from @infrared-city/infrared-sdk.

preparedWeatherIdentity(payload): string

The weather identity of a prepared payload: the value runArea records on the schedule, computed without submitting anything.

Pass the output of prepareAnalysisPayload or prepareAreaPayload, not a runArea input. The prepared payload holds the weather arrays whichever source produced them: a parsed file, the public catalog's records or your own arrays.

Parameters

Parameter	Type	Description
`payload`	`Readonly`<`Record`<`string`, `unknown`>>	A prepared analysis payload.

Returns

string

The identity string of the weather the payload submits.

Throws

when the payload carries no location, no time window or no weather column.

previewAreaBatches

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

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

Preview the jobs a runArea(service, input, polygon, options) call would submit, without submitting anything.

It reports the real number of jobs, which on a facade (analysisSurfaces) request can exceed the tile count because a tile may split into several billed batches. On a grid request it gives one job per tile, like previewArea. Most callers want client.previewAreaBatches(input, polygon, options), which passes client.jobs and client.billing.

Parameters

Parameter	Type	Description
`service`	`AreaJobsService`	The jobs service the plan is prepared against, for example `client.jobs`.
`billing`	\{ `quote`: `Promise`<`PriceQuote`>; \}	The service that prices a job, for example `client.billing`.
`billing.quote`	-
`input`	`RunAreaInputLike`	The analysis request fields.
`polygon`	`Polygon`	The area to analyse.
`options`	`RunAreaOptions`	The same run options `runArea` takes.

Returns

Promise<AreaBatchPreview>

The tile count, planned job count, estimated time and cost, and the sensor count for a facade request.

RetryPolicy

Import from @infrared-city/infrared-sdk.

The SDK's retry and resend limits, read-only.

Properties

Property	Modifier	Type	Description
`failureAdvice`	`readonly`	`Readonly`<`Record`<`TileFailureKind`, `string`>>	What to do about a tile of each `TileFailure.kind`. The keys are every kind.
`maxAttempts`	`readonly`	`number`	Attempts (keys) of one tile, the first included.
`submitMaxSends`	`readonly`	`number`	Sends of one submit that may have a job (5xx, 408, 409, network), the first included.

retryPolicy

Import from @infrared-city/infrared-sdk.

retryPolicy(): RetryPolicy

The SDK's retry and resend limits, read-only. A new object on every call; changing it changes nothing in the SDK.

Returns

RetryPolicy

RunAndWaitOptions

Import from @infrared-city/infrared-sdk.

Options for running an analysis and waiting for its result, when the request may be split into parts.

Extends

PartsWaitOptions

Properties

Property	Modifier	Type	Description	Inherited from
`archive?`	`readonly`	`DecompressResultArchiveOptions`	Size limits for the downloaded result archive (as `jobs.decompress`), for every analysis.	-
`maxParts?`	`readonly`	`number`	The most jobs the run may submit. `1` turns splitting off: the request is sent as one job, exactly as `analyses.execute` sends it. A plan with more parts than a larger value is refused before any request. Default: no limit.	`PartsWaitOptions`.`maxParts`
~~`maxWorkers?`~~	`readonly`	`number`	Deprecated No effect: the engine sets the widths. Removed in 2.0.	`PartsWaitOptions`.`maxWorkers`
`onAccepted?`	`readonly`	(`jobId`, `partKey`) => `void`	Called with the job id and part key of each part the server accepts. An observer only: use it to store job ids before the run returns.	`PartsWaitOptions`.`onAccepted`
`onPoll?`	`readonly`	`OnPollCallback`	Called with one job's status after each poll. Not called for a multi-part run, which polls all parts together: use `onProgress` there.	-
`onProgress?`	`readonly`	(`state`) => `void`	Called with the progress of the run each time the parts are polled.	`PartsWaitOptions`.`onProgress`
`resultFormat?`	`readonly`	`DaylightResultFormat`	The format of a daylight-factor result. `"irbf"`: a `DaylightFactorResult` (typed-array views, with `toJson()` on demand); parts ask the server for binary results when it offers them, else JSON, which is converted into the same frame. `"json"`: the JSON value. Unset: `DEFAULT_DAYLIGHT_RESULT_FORMAT`. Other analyses ignore it.	`PartsWaitOptions`.`resultFormat`
`retryFrom?`	`readonly`	`PartsSchedule`	A schedule from an earlier run of the same request (its `requestDigest` must match). Only the parts that failed (a failed submission or a failed job) are sent again; a part whose submission outcome is unknown never is.	`PartsWaitOptions`.`retryFrom`
`signal?`	`readonly`	`AbortSignal`	Aborts the run.	`PartsWaitOptions`.`signal`
`timeout?`	`readonly`	`number`	Seconds to wait for every part. Default 900, the same as for one job. Checked before any request is sent.	`PartsWaitOptions`.`timeout`
`transport?`	`readonly`	`"json"` \	`"binary"`	How the parts are sent, as for `analyses.execute`. Unset (the default) picks the route automatically from what the server supports: the binary route, where the scene is uploaded once, or JSON. `"json"` keeps every part on JSON; `"binary"` sends the request as a single job and never splits it.	`PartsWaitOptions`.`transport`
`webhookEvents?`	`readonly`	readonly `string`\[\]	The job events that trigger `webhookUrl`.	`PartsWaitOptions`.`webhookEvents`
`webhookUrl?`	`readonly`	`string`	A URL the API calls when a job reaches one of `webhookEvents`.	`PartsWaitOptions`.`webhookUrl`

runArea

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

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

Plans an area run for a polygon and submits it: tiles the polygon, builds each tile's request and sends one job per tile (or per batch of facade sensors).

Returns as soon as the jobs are submitted; poll the jobs with checkAreaState and merge the results with mergeAreaJobs, or use InfraredClient.runAreaAndWait to do all three. Every tile is a billed job, so size the run first with previewAreaBatches.

Parameters

Parameter	Type	Description
`service`	`AreaJobsService`	The jobs service that sends the jobs, for example `client.jobs`.
`input`	`RunAreaInput`	The analysis request: `analysisType` plus the analysis's own parameters.
`polygon`	`Polygon`	The GeoJSON `Polygon` to analyse.
`options`	`RunAreaOptions`	The run options (see `RunAreaOptions`).

Returns

Promise<AreaSchedule>

The frozen schedule of the run, to poll, merge or save.

Throws

when the unsupported binaryResults option is passed.

Throws

when terrainContextMarginM is not a finite non-negative number.

Throws

when retryFrom was saved with a different transport or terrain margin.

Throws

when the API accepted a job with an invalid geometry reference.

RunAreaAndWaitOptions

Import from @infrared-city/infrared-sdk.

Options for InfraredClient.runAreaAndWait: everything runArea takes, plus the merge options.

Extends

RunAreaOptions.AreaMergeOptions

Properties

Property	Modifier	Type	Description	Inherited from
`areaTimeout?`	`readonly`	`number`	`runAreaAndWait` only: seconds to wait for the whole run before it throws `AreaTimeoutError`. A positive number; default 3600.	`RunAreaOptions`.`areaTimeout`
`block?`	`readonly`	`number`	Largest block, in cells per side, that the directional strategies process at once; at least 1. It trades speed against memory only: the result is the same for any value. Default 928.	`AreaMergeOptions`.`block`
`buildings?`	`readonly`	`AreaBuildings` \	`Readonly`<`Record`<`string`, `unknown`>>	The target buildings: an `AreaBuildings` from `BuildingsService.getBuildingsInArea`, or a bare `{buildingId: mesh}` map. An `AreaBuildings` carries `origin` — the frame its bodies are in — and the payload path re-anchors from that origin into this run's site frame, so buildings acquired once for a large area can be run as several sub-areas. A bare map carries no frame and is assumed to be in this polygon's frame already: acquire with the same polygon you run.	`RunAreaOptions`.`buildings`
`contextBufferM?`	`readonly`	`number`	Metres added round each tile's detailed area (tile core plus the detailed-geometry margin). In each tile, the `contextGeometry` triangles inside that area are removed and the rest of each mesh stays, so a merged city mesh or a ground sheet given as context keeps its parts outside the area. The SDK logs one warning with the count. Default 10; 0 = no extra buffer.	`RunAreaOptions`.`contextBufferM`
`contextReachM?`	`readonly`	`number` \	`null`	Metres outside each tile's core within which a `contextGeometry` mesh is sent with that tile (a square box, core ± reach). Default 600. Must be larger than the tile margin plus `contextBufferM`, because the context inside that area is removed. `null` sends every mesh to every tile: use it when you choose the context yourself. A changed value changes the tile bodies and their hashes.	`RunAreaOptions`.`contextReachM`
`groundMaterials?`	`readonly`	`Readonly`<`Record`<`string`, `unknown`>> \	`AreaGroundMaterials`	The ground materials: an `AreaGroundMaterials` from `GroundMaterialsService.getArea`, or a bare `{layer: collection}` map. The acquired object carries its read margin, checked as for `vegetation`.	`RunAreaOptions`.`groundMaterials`
`known?`	`readonly`	`Readonly`<`Record`<`string`, `TileJobStatus`>>	Job id to status, from your own earlier status checks. A job recorded as `"completed"` or `"failed"` is not asked about again, so a poll loop that ends with a merge sends no second round of status requests.	`AreaMergeOptions`.`known`
`logger?`	`readonly`	`Logger`	Receives warnings, such as an unrecognised request key. `InfraredClient` passes its own logger.	`RunAreaOptions`.`logger`
`maxSensorsPerJob?`	`readonly`	`number`	Facade runs only: the most retained sensors one job may carry, a whole number from 1 to 250 000 (the default target). A smaller cap gives more, smaller jobs; each is still an exact, verified count, so a preview with the same cap reports the same jobs and sensors. A retry may omit it or repeat the saved value; a different value is refused.	`RunAreaOptions`.`maxSensorsPerJob`
`maxTilesOverride?`	`readonly`	`number`	Raises the limit on how many non-empty tiles one run may cover. A run over the limit is refused before anything is submitted, and the message gives the number to pass here. Each tile is a billed job, so size the run with a preview first.	`RunAreaOptions`.`maxTilesOverride`
~~`maxWorkers?`~~	`readonly`	`number`	Deprecated No effect: the engine sets the widths. Removed in 2.0.	`RunAreaOptions`.`maxWorkers`
`onAccepted?`	`readonly`	(`jobId`, `tileKey`) => `void`	Called once for each job id the run records, at the moment it records it, with the tile key. A synchronous observer: it only reports, the run does not wait for a returned promise, and an error thrown here is ignored, so the schedule never changes. Use it to store accepted job ids before `runArea` returns (the worker helper sends them to the page this way); a failed store is the caller's to retry.	`RunAreaOptions`.`onAccepted`
`onProgress?`	`readonly`	(`state`) => `void`	Called with the run's counts after each submission and status update.	`RunAreaOptions`.`onProgress`
`packing?`	`readonly`	`"regular"` \	`"fast"`	How a facade run puts buildings into jobs. `"regular"` (default) counts the sensors of every group of buildings exactly. `"fast"` counts each building once, alone, and packs the buildings by the sum of those counts: planning is faster, and a job holds at most 290,000 sensors (or `maxSensorsPerJob`). The values of each sensor are the same; only which job carries a building changes, so the number of jobs can differ. A retry replays the saved jobs.	`RunAreaOptions`.`packing`
`retries?`	`readonly`	`number`	Retry rounds after the run completes, when it left submissions that failed, jobs that failed while computing, or submissions whose outcome is unknown. Default 1; `0` turns retrying off. Each round resubmits only what needs it and waits again; a round that resubmits nothing ends the retrying early. A run is never retried after the API refused it with status 402 (payment required).	-
`retryFrom?`	`readonly`	`AreaSchedule`	The schedule of an earlier run of the same area and analysis. The run continues from that saved schedule instead of starting a new one.	`RunAreaOptions`.`retryFrom`
`signal?`	`readonly`	`AbortSignal`	Aborts the run.	`RunAreaOptions`.`signal`
`strategy?`	`readonly`	`"default"` \	`"directional"` \	`"directional_blend"`	How overlapping tiles are blended. Default `"default"`. `"directional"` and `"directional_blend"` apply to wind-speed analyses only and require `windDirectionDeg`.	`AreaMergeOptions`.`strategy`
`terrainContext?`	`readonly`	`TerrainContext`	Not for callers: the SDK builds the terrain context itself. Passing it is refused; use `terrainContextMarginM` instead.	`RunAreaOptions`.`terrainContext`
`terrainContextMarginM?`	`readonly`	`number`	Metres of terrain read beyond each tile so its edges are seated on real ground. Default 0 m; the analysis's own minimum (solar family: 128 m) wins when it is larger. A retry must repeat the saved value.	`RunAreaOptions`.`terrainContextMarginM`
`transport?`	`readonly`	`"json"` \	`"binary"`	How the request is sent. Unset: binary, or JSON for an analysis that has no binary route; a retry keeps the transport of the run it continues. Pass `"json"` to force JSON.	`RunAreaOptions`.`transport`
`vegetation?`	`readonly`	`Readonly`<`Record`<`string`, `unknown`>> \	`AreaVegetation`	The trees: an `AreaVegetation` from `VegetationService.getArea`, or a bare `{key: feature}` map. The acquired object carries the read margin it was fetched with, and a run whose analysis needs a wider one is refused.	`RunAreaOptions`.`vegetation`
`webhookEvents?`	`readonly`	readonly `string`\[\]	The job events that trigger `webhookUrl`.	`RunAreaOptions`.`webhookEvents`
`webhookUrl?`	`readonly`	`string`	A URL the API calls when a job reaches one of `webhookEvents`.	`RunAreaOptions`.`webhookUrl`
`windDirectionDeg?`	`readonly`	`number`	Wind direction in degrees. Required for the directional strategies.	`AreaMergeOptions`.`windDirectionDeg`

RunAreaInput

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

RunAreaInput = Readonly<Record<string, unknown>> & \{ analysis-type?: never; analysisType: string; \} \| \{ analysis-type: string; analysisType?: never; \}

The analysis request runArea takes: analysisType (or the wire key "analysis-type") plus the analysis's own parameters.

RunAreaInputLike

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

RunAreaInputLike = Readonly<Record<string, unknown>>

The analysis request fields previewAreaBatches accepts: an object keyed by request field name.

RunAreaOptions

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

Options for runArea, runAreaAndWait and previewAreaBatches.

Extended by

RunAreaAndWaitOptions

Properties

Property	Modifier	Type	Description
`areaTimeout?`	`readonly`	`number`	`runAreaAndWait` only: seconds to wait for the whole run before it throws `AreaTimeoutError`. A positive number; default 3600.
`buildings?`	`readonly`	`AreaBuildings` \	`Readonly`<`Record`<`string`, `unknown`>>	The target buildings: an `AreaBuildings` from `BuildingsService.getBuildingsInArea`, or a bare `{buildingId: mesh}` map. An `AreaBuildings` carries `origin` — the frame its bodies are in — and the payload path re-anchors from that origin into this run's site frame, so buildings acquired once for a large area can be run as several sub-areas. A bare map carries no frame and is assumed to be in this polygon's frame already: acquire with the same polygon you run.
`contextBufferM?`	`readonly`	`number`	Metres added round each tile's detailed area (tile core plus the detailed-geometry margin). In each tile, the `contextGeometry` triangles inside that area are removed and the rest of each mesh stays, so a merged city mesh or a ground sheet given as context keeps its parts outside the area. The SDK logs one warning with the count. Default 10; 0 = no extra buffer.
`contextReachM?`	`readonly`	`number` \	`null`	Metres outside each tile's core within which a `contextGeometry` mesh is sent with that tile (a square box, core ± reach). Default 600. Must be larger than the tile margin plus `contextBufferM`, because the context inside that area is removed. `null` sends every mesh to every tile: use it when you choose the context yourself. A changed value changes the tile bodies and their hashes.
`groundMaterials?`	`readonly`	`Readonly`<`Record`<`string`, `unknown`>> \	`AreaGroundMaterials`	The ground materials: an `AreaGroundMaterials` from `GroundMaterialsService.getArea`, or a bare `{layer: collection}` map. The acquired object carries its read margin, checked as for `vegetation`.
`logger?`	`readonly`	`Logger`	Receives warnings, such as an unrecognised request key. `InfraredClient` passes its own logger.
`maxSensorsPerJob?`	`readonly`	`number`	Facade runs only: the most retained sensors one job may carry, a whole number from 1 to 250 000 (the default target). A smaller cap gives more, smaller jobs; each is still an exact, verified count, so a preview with the same cap reports the same jobs and sensors. A retry may omit it or repeat the saved value; a different value is refused.
`maxTilesOverride?`	`readonly`	`number`	Raises the limit on how many non-empty tiles one run may cover. A run over the limit is refused before anything is submitted, and the message gives the number to pass here. Each tile is a billed job, so size the run with a preview first.
~~`maxWorkers?`~~	`readonly`	`number`	Deprecated No effect: the engine sets the widths. Removed in 2.0.
`onAccepted?`	`readonly`	(`jobId`, `tileKey`) => `void`	Called once for each job id the run records, at the moment it records it, with the tile key. A synchronous observer: it only reports, the run does not wait for a returned promise, and an error thrown here is ignored, so the schedule never changes. Use it to store accepted job ids before `runArea` returns (the worker helper sends them to the page this way); a failed store is the caller's to retry.
`onProgress?`	`readonly`	(`state`) => `void`	Called with the run's counts after each submission and status update.
`packing?`	`readonly`	`"regular"` \	`"fast"`	How a facade run puts buildings into jobs. `"regular"` (default) counts the sensors of every group of buildings exactly. `"fast"` counts each building once, alone, and packs the buildings by the sum of those counts: planning is faster, and a job holds at most 290,000 sensors (or `maxSensorsPerJob`). The values of each sensor are the same; only which job carries a building changes, so the number of jobs can differ. A retry replays the saved jobs.
`retryFrom?`	`readonly`	`AreaSchedule`	The schedule of an earlier run of the same area and analysis. The run continues from that saved schedule instead of starting a new one.
`signal?`	`readonly`	`AbortSignal`	Aborts the run.
`terrainContext?`	`readonly`	`TerrainContext`	Not for callers: the SDK builds the terrain context itself. Passing it is refused; use `terrainContextMarginM` instead.
`terrainContextMarginM?`	`readonly`	`number`	Metres of terrain read beyond each tile so its edges are seated on real ground. Default 0 m; the analysis's own minimum (solar family: 128 m) wins when it is larger. A retry must repeat the saved value.
`transport?`	`readonly`	`"json"` \	`"binary"`	How the request is sent. Unset: binary, or JSON for an analysis that has no binary route; a retry keeps the transport of the run it continues. Pass `"json"` to force JSON.
`vegetation?`	`readonly`	`Readonly`<`Record`<`string`, `unknown`>> \	`AreaVegetation`	The trees: an `AreaVegetation` from `VegetationService.getArea`, or a bare `{key: feature}` map. The acquired object carries the read margin it was fetched with, and a run whose analysis needs a wider one is refused.
`webhookEvents?`	`readonly`	readonly `string`\[\]	The job events that trigger `webhookUrl`.
`webhookUrl?`	`readonly`	`string`	A URL the API calls when a job reaches one of `webhookEvents`.

SCHEDULE_CONTRACT_VERSION

Import from @infrared-city/infrared-sdk.

const SCHEDULE\_CONTRACT\_VERSION: 13 = 13

The version of the schedule record format this SDK writes into new schedules (AreaSchedule.scheduleContractVersion).

It is raised whenever a field a retry guard depends on is added or changes meaning. A retry of a schedule written under an older version may be refused by name, with guidance to start a fresh run.

StatusSweep

Import from @infrared-city/infrared-sdk.

The answer to one batched status request for many jobs.

Properties

Property	Modifier	Type	Description
`batched`	`readonly`	`boolean`	Whether the service answered in the batched form.
`failedIds?`	`readonly`	readonly `string`\[\]	Ids deferred to the next sweep because the service answered 429 or a 5xx.
`lacking`	`readonly`	`boolean`	Whether the service showed that it does not offer batched status.
`refusedStatus?`	`readonly`	`number`	The HTTP status of a chunk the service refused for good (401, 403, other 4xx but 404/429).
`retryAfterS?`	`readonly`	`number`	The longest `Retry-After` those failures carried, in seconds.
`statuses`	`readonly`	`Map`<`string`, `Job`>	The status of each answered job, keyed by job id.
`unanswered`	`readonly`	`string`\[\]	Ids this request did not settle; read each of these with a single-job status call.

submitAreaPlan

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

submitAreaPlan(service, plan, options?): Promise<AreaSchedule>

Submits an already validated plan, one job per entry, and returns the schedule of the run.

A request whose outcome is unknown is sent again with the same idempotency key a few times; after that it is recorded in the schedule as uncertain so you can decide. Failed submissions are recorded too. Pass options.retryFrom to continue a saved schedule.

Parameters

Parameter	Type	Description
`service`	`AreaJobsService`	The jobs service that sends the jobs, for example `client.jobs`.
`plan`	`AreaSubmissionPlan`	The submission plan from `planAreaSubmission`.
`options`	`RunAreaOptions`	The run options: `signal`, `onAccepted`, `onProgress`, `retryFrom`.

Returns

Promise<AreaSchedule>

The frozen schedule of the run.

Throws

when the API accepted a job with an invalid geometry reference, or retryFrom records one.

Throws

when retryFrom is a legacy schedule with an uncertain capability probe.

SubmitPreparedOptions

Import from @infrared-city/infrared-sdk.

The options of JobsService.submitPrepared; area runs set them.

Properties

Property	Modifier	Type	Description
`beforeDispatch?`	`readonly`	() => `void`	-
`idempotencyKey?`	`readonly`	`string`	The `Idempotency-Key` that makes a retried send safe; unset for a single submit.
`signal?`	`readonly`	`AbortSignal`	-
`stages?`	`readonly`	`object`	The upload and POST slots of one area run; unset for a single submit.
`stages.post`	`readonly`	<`T`>(`send`) => `Promise`<`T`>	-
`stages.uploaded`	`readonly`	() => `void`	-

TileJobStatus

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

TileJobStatus = "pending" \| "running" \| "completed" \| "failed" \| "skipped"

The state of one tile's job: "pending", "running", "completed", "failed", or "skipped" (not run, or no longer polled).

TilePosition

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

Where one tile sits in the tile grid.

Properties

Property	Modifier	Type	Description
`col`	`readonly`	`number`	Column of the tile in the tile grid.
`row`	`readonly`	`number`	Row of the tile in the tile grid.
`tileId`	`readonly`	`string`	Identifier of the tile.

TileProgress

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

A progress report for one tile, passed to a progress callback as a run proceeds.

Properties

Property	Modifier	Type	Description
`col`	`readonly`	`number`	Column of the tile in the tile grid.
`completedCount`	`readonly`	`number`	Number of tiles completed so far.
`elapsedTime`	`readonly`	`number`	Time since the run started, in seconds.
`finishedCount`	`readonly`	`number`	Number of tiles that have finished so far.
`row`	`readonly`	`number`	Row of the tile in the tile grid.
`status`	`readonly`	`"running"` \	`"failed"` \	`"completed"` \	`"skipped"`	State of the tile when reported.
`tileId`	`readonly`	`string`	Identifier of the tile.
`totalCount`	`readonly`	`number`	Total number of tiles in the run.