# Relynk resources

Finding levels, rooms and equipment in a building and walking the relationships between them.

Each function is a POST to the path shown, relative to the connector's base URL, with its body as JSON; the response is JSON. The types below are JSDoc.

Notes:
- Add `?tenantId=<id>` to every call when `GET /me` lists more than one tenant for the user.
- Errors are `{ "error": { "code", "message" } }`; a 400 message says how to change the request.
- Lists page with `nextCursor` (or `offset` and `hasMore`). Times are Europe/Oslo, ranges half-open `[from, to)`, ids are UUIDs. `null` means no data.
- A path never changes its contract; a new version gets a new path.

## POST /resources.list/v1

Resources (buildings, levels, rooms, equipment, points, …) filtered by building, type, name or id. Pages by id: pass nextCursor back until it is null. For the points of equipment or rooms use points.list; for connected resources use resources.related.

Body: `ResourcesListInput`. Response: `ResourcesListOutput`.

```js
/**
 * @typedef {Object} ResourcesListInput
 * @property {string} [buildingId] A building id (from buildings.list). Matches the building itself and everything that is part of it (uuid)
 * @property {Array<string>} [typeKeys] Only these types and their subtypes, e.g. ["rec_Room"] (keys from resourceTypes.list) (min items 1, max items 100)
 * @property {Array<"Asset" | "Space" | "Collection" | "Point" | "Unit">} [mainTypes] Only these main types (min items 1)
 * @property {Array<string>} [ids] Only these resources (min items 1, max items 1000)
 * @property {string} [search] Only names containing this text, ignoring case (min length 1, max length 200)
 * @property {number} [limit=200] (min 1, max 1000)
 * @property {string} [cursor] nextCursor from the previous page; omit for the first page (uuid)
 */

/**
 * @typedef {Object} ResourcesListOutput
 * @property {Array<ResourcesListOutputResourcesItem>} resources (max items 1000)
 * @property {string | null} nextCursor Pass as cursor for the next page; null on the last
 */

/**
 * @typedef {Object} ResourcesListOutputResourcesItem
 * @property {string} id
 * @property {string} name
 * @property {string} typeKey
 * @property {string} typeName
 * @property {string} mainType Asset, Space, Collection, Point or Unit
 * @property {string | null} buildingId The building it is part of; null for buildings
 */
```

## POST /resources.related/v1

Resources connected to the given ones by one relationship, following it up to maxDepth steps. One row per (fromId, related resource) at its shortest depth. Common relationships: brick_Has_Part (building → levels → rooms; "in" = Is Part Of), brick_Feeds (air handling unit → terminal units → rooms; "in" = Is Fed By), brick_Has_Sub_Meter, brick_Is_Metered_By, rec_Located_In, relynk_Virtual_Meter_Calculated_From. resourceTypes.relationships shows which ones a building uses. For points use points.list with resourceIds.

Body: `ResourcesRelatedInput`. Response: `ResourcesRelatedOutput`.

```js
/**
 * @typedef {Object} ResourcesRelatedInput
 * @property {Array<string>} fromIds Resources to start from (min items 1, max items 200)
 * @property {string} relationship Relationship key, e.g. "brick_Has_Part"
 * @property {"out" | "in"} [direction="out"] "out" follows the relationship as named (Has Part); "in" follows its inverse (Is Part Of)
 * @property {number} [maxDepth=1] Steps to follow; e.g. 2 for building → levels → rooms via brick_Has_Part (min 1, max 10)
 * @property {Array<string>} [targetTypeKeys] Only these types and their subtypes, e.g. ["rec_Room"] (keys from resourceTypes.list) (min items 1, max items 100)
 * @property {Array<"Asset" | "Space" | "Collection" | "Point" | "Unit">} [targetMainTypes] Only these main types (min items 1)
 * @property {number} [limit=1000] (min 1, max 5000)
 */

/**
 * @typedef {Object} ResourcesRelatedOutput
 * @property {Array<ResourcesRelatedOutputRelatedItem>} related (max items 5000)
 * @property {boolean} truncated True when limit cut the result; narrow the filters or raise limit
 */

/**
 * @typedef {Object} ResourcesRelatedOutputRelatedItem
 * @property {string} id
 * @property {string} name
 * @property {string} typeKey
 * @property {string} typeName
 * @property {string} mainType Asset, Space, Collection, Point or Unit
 * @property {string | null} buildingId The building it is part of; null for buildings
 * @property {string} fromId Which of fromIds this was reached from
 * @property {number} depth Steps from fromId
 */
```