Extension SDK

The Extension SDK enables you to create custom logic that can be run inside Editor or headless Worker. It provides easy to use but powerful methods to query, mutate, draw, interact, compute or export a layout.

Check the Setup guide to learn how to work locally and deploy your first extension.

Hosts

Editor

Editor extensions can provide their own UI, rely on dialogs, or run as headless scripts.

export async function run({ hostApi, container }) {
  const spaces = await hostApi.getSpaces()
  container.innerText = `Space count: ${spaces.length}`
}

Cloud Worker

Worker extensions are accessible via an API and can leverage parameters. They are also exposed as tools for your organization by the MCP Server.

export async function run({ hostApi, parameters }) {
  const subCategory = parameters?.subCategory || 'meetingRoom'
  const spaces = await hostApi.getSpaces({ where: { subCategory } })
  return {
    spaceCount: spaces.length,
    subCategory
  }
}

curl -X POST https://api.archilogic.com/v2/floor/:floorId/extensions/:extensionId \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{ "parameters": { "subCategory": "privateOffice" } }'

Host API

Every extension exports a run function which is executed by the host in a sandbox. The HostApi instance is provided as an argument which is the main interface for extensions allowing you to run commands that are executed by the host.

While editor extensions can subscribe to events and provide their own UI which is loaded in an iframe, worker extensions need to return something in the run function for the endpoint to capture it.

JavaScript

export async function run({ hostApi }) {
  const meetingRooms = await hostApi.getSpaces({
    where: { program: { eq: 'meet' }, seatCapacity: { gte: 4, lte: 6 } }
  })
}

TypeScript

import type { HostApi } from '@archilogic/extension-sdk'

export async function run({ hostApi }: { hostApi: HostApi }) {
  const meetingRooms = await hostApi.getSpaces({
    where: { program: { eq: 'meet' }, seatCapacity: { gte: 4, lte: 6 } }
  })
}

Events

Hosts Editor

You can register event handlers for various events at run time

hostApi.on('layout-change', ({ operations }) => {})
hostApi.on('selection-change', ({ selectedNodes }) => {})
hostApi.on('canvas-click', ({ position, nodeId }) => {})

Queries

Hosts EditorCloud Worker

Query methods have powerful filter options similar to the GraphQL API.
They have the same interface as the Floor plan SDK queries, except being async.

Get elements

Query elements with the getElements method by various properties and optionally select the shape of the returned objects.

const largeWindows = await hostApi.getElements({
  where: { type: 'element:window', dimensions: { length: { gte: 3 } } }
})

Get element by id

Retrieve specific properties from an element with getElementById

const { dimensions, boundingBox } = await hostApi.getElementById({
  id: '<asset-id>',
  select: { boundingBox: true, dimensions: true }
})

Get spaces

Query spaces with the getSpaces method by various properties and optionally select the shape of the returned objects.

const spaces = await hostApi.getSpaces({
  where: { seatCapacity: { gte: 5 } }
})

Get space by id

Retrieve specific properties from a space with getSpaceById

const { labelPoint, contour, elements } = await hostApi.getSpaceById({
  id: '<space-id>',
  select: { labelPoint: true, contour: true, elements: true }
})

Get products

Query products with the getProducts method by various properties and optionally select the shape of the returned objects.

const chairCounts = await hostApi.getProducts({
  select: { id: true, count: true },
  where: { subCategory: 'taskChair' }
})

Operations

Hosts Editor

Make changes to the layout, like adjusting space meta data or placing assets inside a space. This interface mirrors the operations endpoint.

Create

Create elements in the layout.

await hostApi.runOperations({
  operations: [
    {
      type: 'operation:elementCreate',
      value: {
        type: 'element:asset',
        position: [-2, 0, 3],
        rotation: 45,
        product: '<product-id>'
      }
    }
  ]
})

Update

Update the layout by changing node's properties or creating/removing nodes.

Like the custom attributes of a space.

await hostApi.runOperations({
  operations: [
    {
      type: 'operation:spaceUpdate',
      id: '<space-id>',
      value: { customAttributes: { isBooked: true } }
    }
  ]
})

Delete

Remove elements from the layout.

await hostApi.runOperations({
  operations: [
    {
      type: 'operation:elementRemove',
      id: '<element-id>'
    }
  ]
})

Drawing

Hosts Editor

Add plan layer

const layerRef = await hostApi.addPlanLayer({ id: 'my-layer' })

Add plan graphics

const layerRef = await hostApi.addPlanGraphic({
  shapes: [
    {
      type: 'curve:circle',
      radius: 1,
      position: [1, 0]
    }
  ],
  layerId: 'my-layer'
})

Set plan config

await hostApi.setPlanConfig({
  theme: {
    byFilter: [
      {
        where: { customAttributes: { isBooked: { eq: true } } },
        fill: '#FF8800'
      },
      {
        where: { customAttributes: { isBooked: { eq: false } } },
        fill: '#00FF88'
      }
    ]
  }
})

Interact

Hosts Editor

Zoom to node

await hostApi.zoomToNode({ nodeId: '<space-id>' })

Zoom extents

await hostApi.zoomExtents({ margin: 2, animate: true })

Select nodes

await hostApi.selectNodes({ nodeIds: ['<space-1>'] })

Dialogs

Hosts Editor

Confirm

const isConfirmed = await hostApi.confirm({
  title: 'Remove all assets',
  confirmLabel: 'Yes',
  cancelLabel: 'No'
})

Prompt

const { format } = await hostApi.prompt({
  title: 'Export format',
  parameters: {
    format: {
      label: 'Format',
      type: 'Select',
      options: ['JPG', 'PNG'],
      default: 'JPG'
    }
  }
})

Compute Coming soon

Hosts EditorCloud Worker

Run complex tasks like way finding.

Get path

Compute the fastest path from A to B by avoiding 'Hub' spaces

const path = await hostApi.getPath({
  start: [3, 4.5],
  target: [25, 123.5],
  excludeSpaces: {
    where: { subCategory: { in: ['hub'] } }
  }
})

Find closest space

Find the closest space with seat capacity greater than 4 that is bookable

const path = await hostApi.findClosestSpace({
  start: [3, 4.5],
  where: {
    seatCapacity: { gte: 4 },
    customAttributes: { isBooked: { eq: false } }
  }
})

Exports Coming soon

Hosts EditorCloud Worker

Export the layout including the custom graphics and style to various formats

PDF

const path = await hostApi.exportPdf({
  orientation: 'landscape',
  format: 'A4',
  units: 'mm'
})

DXF

const path = await hostApi.exportDxf()

SVG

const path = await hostApi.exportSvg()

GeoJSON

const path = await hostApi.exportGeoJson()

IMDF

const path = await hostApi.exportImdf()

IFC

const path = await hostApi.exportIfc()

GLTF

const path = await hostApi.exportGltf()