Routes and linked accessories

Build saved routes and linked arrangements, then review activation separately.

Source 0.1.0 Private source package

How the calls fit together

Read the saved definition and activation analysis. Use the reviewed revision and original intent for a deliberate activation, without automatic replay.

JavaScript examples

Supply your configured client. Each call awaits a decoded result; errors pass to your caller. These identifiers and values are fictional. Use selected development records and review every change before running it. Opening this page sends no API requests.

See the complete TypeScript workflow · Explore the Node starter

routes.list

Reads the complete bounded route collection from one authorised snapshot.

const result = await client.routes.list(
  "23",
  "31",
  {}
);

TypeScript parameters and return type

accountId · required: string
Owning account.
layoutId · required: string
Original layout.
options · optional: RailDeckRequestControlOptions
Cancellation/deadline.

Returns Promise<RouteListResponse>.

Example evidence: Retained SDK transport fixture.

routes.saveLinkedAccessoryOrder

Saves the complete reviewed Linked accessory order without operating its members.

const result = await client.routes.saveLinkedAccessoryOrder(
  "23",
  "31",
  {
    "requestId": "7239eabc-0000-4000-8000-000000000003",
    "reviewedIds": [
      "8",
      "9"
    ],
    "orderedIds": [
      "9",
      "8"
    ]
  },
  {}
);

TypeScript parameters and return type

accountId · required: string
Owning account.
layoutId · required: string
Original layout.
input · required: ReviewedOrderCommand
Original reviewed permutation.
options · optional: RailDeckRequestControlOptions
Request lifetime.

Returns Promise<ReviewedOrderReceipt>.

Example evidence: Retained SDK transport fixture.

routes.analyseActivation

Analyses whether one saved route will change accessory state.

const result = await client.routes.analyseActivation(
  "account-1",
  "layout-1",
  "route-2"
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the layout.
layoutId · required: RailDeckIdentifier
Layout containing the route.
routeId · required: RailDeckIdentifier
Route to analyse.

Returns Promise<RailDeckRouteActivationAnalysis>.

Example evidence: Retained SDK transport fixture.

routes.activate

Activates one saved route through the live command path.

const result = await client.routes.activate(
  "1",
  "1",
  "1",
  {
    "requestId": "b623d76d-c1d0-4c6d-9d2a-2b9521b20c36",
    "expectedRevision": 5,
    "priority": null,
    "expiresInMs": 10000
  },
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the layout.
layoutId · required: RailDeckIdentifier
Layout containing the route.
routeId · required: RailDeckIdentifier
Route to activate.
input · required: RailDeckRouteActivationInput
Original request identity, reviewed revision and optional delivery settings.
options · optional: RailDeckRequestControlOptions
Cancellation and deadline; failure does not authorise a new activation.

Returns Promise<RailDeckRouteActivationResponse>.

Example evidence: Retained SDK transport fixture.

routes.listLinkedAccessories

Lists bounded summaries without downloading every named choice's member plan.

const result = await client.routes.listLinkedAccessories(
  "1",
  "1",
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Owning account.
layoutId · required: RailDeckIdentifier
Original layout.
options · optional: RailDeckRequestControlOptions
Cancellation/deadline.

Returns Promise<RailDeckLinkedAccessoryListResponse>.

Example evidence: Retained SDK transport fixture.

routes.createLinkedAccessory

Creates complete authored named choices under one immutable original request.

const result = await client.routes.createLinkedAccessory(
  "23",
  "31",
  {
    "requestId": "a4000000-bbbb-4ccc-8ddd-000000000001",
    "definition": {
      "displayName": "{{fixtureDisplayName}}",
      "description": "Open the station.\n\nKeep the goods yard separate.",
      "enabled": true,
      "metadata": {
        "retained": "Group information"
      },
      "choices": [
        {
          "choiceId": "a4000000-bbbb-4ccc-8ddd-000000000002",
          "displayName": "Arrangement a4000000-bbbb-4ccc-8ddd-000000000002",
          "steps": [
            {
              "accessoryId": "91",
              "targetState": "closed",
              "sequenceOrder": 1,
              "delayMs": 0,
              "metadata": {}
            },
            {
              "accessoryId": "92",
              "targetState": "thrown",
              "sequenceOrder": 2,
              "delayMs": 0,
              "metadata": {}
            },
            {
              "accessoryId": "93",
              "targetState": "on",
              "sequenceOrder": 3,
              "delayMs": 0,
              "metadata": {}
            },
            {
              "accessoryId": "94",
              "targetState": "off",
              "sequenceOrder": 4,
              "delayMs": 0,
              "metadata": {}
            }
          ]
        },
        {
          "choiceId": "a4000000-bbbb-4ccc-8ddd-000000000003",
          "displayName": "Arrangement a4000000-bbbb-4ccc-8ddd-000000000003",
          "steps": [
            {
              "accessoryId": "91",
              "targetState": "thrown",
              "sequenceOrder": 1,
              "delayMs": 0,
              "metadata": {}
            },
            {
              "accessoryId": "92",
              "targetState": "closed",
              "sequenceOrder": 2,
              "delayMs": 0,
              "metadata": {}
            },
            {
              "accessoryId": "93",
              "targetState": "off",
              "sequenceOrder": 3,
              "delayMs": 0,
              "metadata": {}
            },
            {
              "accessoryId": "94",
              "targetState": "on",
              "sequenceOrder": 4,
              "delayMs": 0,
              "metadata": {}
            }
          ]
        }
      ]
    }
  },
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Owning account.
layoutId · required: RailDeckIdentifier
Original layout.
input · required: CreateRailDeckLinkedAccessoryInput
Original creation identity and complete named definition.
options · optional: RailDeckRequestControlOptions
Request lifetime without automatic replay.

Returns Promise<LinkedAccessoryMutationReceipt>.

Example evidence: Retained SDK transport fixture.

routes.getLinkedAccessory

Opens one explicit legacy or named saved definition for review.

const result = await client.routes.getLinkedAccessory(
  "1",
  "1",
  "1",
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Owning account.
layoutId · required: RailDeckIdentifier
Original layout.
linkedAccessoryId · required: RailDeckIdentifier
Selected saved group.
options · optional: RailDeckRequestControlOptions
Cancellation/deadline.

Returns Promise<RailDeckLinkedAccessory>.

Example evidence: Retained SDK transport fixture.

routes.updateLinkedAccessory

Replaces a reviewed idle definition, including a deliberate complete legacy upgrade.

const result = await client.routes.updateLinkedAccessory(
  "1",
  "1",
  "1",
  {
    "requestId": "002ed11c-0391-4900-af65-0f3dd51f81ce",
    "expectedRevision": 8,
    "definition": {
      "displayName": "{{fixtureDisplayName}}",
      "description": "Open the station.\n\nKeep the goods yard separate.",
      "enabled": true,
      "metadata": {
        "raildeckLibrary": "signal",
        "retained": "Group information"
      },
      "choices": [
        {
          "choiceId": "a4000000-bbbb-4ccc-8ddd-000000000002",
          "displayName": "Arrangement a4000000-bbbb-4ccc-8ddd-000000000002",
          "steps": [
            {
              "accessoryId": "2",
              "targetState": "closed",
              "sequenceOrder": 1,
              "delayMs": 0,
              "metadata": {}
            },
            {
              "accessoryId": "3",
              "targetState": "thrown",
              "sequenceOrder": 2,
              "delayMs": 0,
              "metadata": {}
            },
            {
              "accessoryId": "1",
              "targetState": "on",
              "sequenceOrder": 3,
              "delayMs": 0,
              "metadata": {}
            },
            {
              "accessoryId": "4",
              "targetState": "off",
              "sequenceOrder": 4,
              "delayMs": 0,
              "metadata": {}
            },
            {
              "accessoryId": "5",
              "targetState": "green",
              "sequenceOrder": 5,
              "delayMs": 0,
              "metadata": {}
            }
          ]
        },
        {
          "choiceId": "a4000000-bbbb-4ccc-8ddd-000000000003",
          "displayName": "Arrangement a4000000-bbbb-4ccc-8ddd-000000000003",
          "steps": [
            {
              "accessoryId": "2",
              "targetState": "thrown",
              "sequenceOrder": 1,
              "delayMs": 0,
              "metadata": {}
            },
            {
              "accessoryId": "3",
              "targetState": "closed",
              "sequenceOrder": 2,
              "delayMs": 0,
              "metadata": {}
            },
            {
              "accessoryId": "1",
              "targetState": "off",
              "sequenceOrder": 3,
              "delayMs": 0,
              "metadata": {}
            },
            {
              "accessoryId": "4",
              "targetState": "on",
              "sequenceOrder": 4,
              "delayMs": 0,
              "metadata": {}
            },
            {
              "accessoryId": "5",
              "targetState": "red",
              "sequenceOrder": 5,
              "delayMs": 0,
              "metadata": {}
            }
          ]
        }
      ]
    }
  },
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Owning account.
layoutId · required: RailDeckIdentifier
Original layout.
linkedAccessoryId · required: RailDeckIdentifier
Originally reviewed group.
input · required: UpdateRailDeckLinkedAccessoryInput
Original request, reviewed revision and complete named choices.
options · optional: RailDeckRequestControlOptions
Request lifetime; uncertain evidence never triggers background replay.

Returns Promise<LinkedAccessoryMutationReceipt>.

Example evidence: Retained SDK transport fixture.

routes.deleteLinkedAccessory

Removes only the deliberately reviewed legacy or named group.

const result = await client.routes.deleteLinkedAccessory(
  "23",
  "31",
  "8",
  {
    "requestId": "a4000000-bbbb-4ccc-8ddd-000000000001",
    "expectedRevision": 5
  },
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Owning account.
layoutId · required: RailDeckIdentifier
Original layout.
linkedAccessoryId · required: RailDeckIdentifier
Originally reviewed group.
input · required: DeleteLinkedAccessoryCommand
Original deletion identity and reviewed revision.
options · optional: RailDeckRequestControlOptions
Cancellation/deadline without automatic mutation replay.

Returns Promise<LinkedAccessoryMutationReceipt>.

Example evidence: Retained SDK transport fixture.

routes.analyseLinkedAccessoryActivation

Analyses whether one linked accessory will change accessory state.

const result = await client.routes.analyseLinkedAccessoryActivation(
  "account-1",
  "layout-1",
  "linked-2"
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the layout.
layoutId · required: RailDeckIdentifier
Layout containing the linked accessory.
linkedAccessoryId · required: RailDeckIdentifier
Linked accessory to analyse.

Returns Promise<RailDeckRouteActivationAnalysis>.

Example evidence: Retained SDK transport fixture.

routes.activateLinkedAccessory

Applies one complete saved named arrangement through the whole-bridge command path.

const result = await client.routes.activateLinkedAccessory(
  "1",
  "1",
  "1",
  {
    "requestId": "82b54bc5-bd6b-41a9-82b1-ebaed84b8b7d",
    "expectedRevision": 13,
    "priority": null,
    "expiresInMs": 2000,
    "choiceId": "a4000000-bbbb-4ccc-8ddd-000000000002"
  },
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the layout.
layoutId · required: RailDeckIdentifier
Layout containing the linked accessory.
linkedAccessoryId · required: RailDeckIdentifier
Linked accessory to activate.
input · required: RailDeckLinkedAccessoryActivationInput
Original request, reviewed revision, stable choice and bounded delivery options.
options · optional: RailDeckRequestControlOptions
Cancellation and deadline; interruption never authorises a fresh command.

Returns Promise<RailDeckLinkedAccessoryActivationResponse>.

Example evidence: Retained SDK transport fixture.

routes.cancelExecution

Cancels a running route or linked-accessory execution.

const result = await client.routes.cancelExecution(
  "account-1",
  "layout-1",
  "command-route-1",
  {
    "reason": "{{reviewedReason}}"
  }
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the layout.
layoutId · required: RailDeckIdentifier
Layout containing the route execution.
commandId · required: RailDeckIdentifier
Parent route execution command to cancel.
input · optional: RailDeckRouteExecutionCancellationInput
Optional human-readable cancellation reason.

Returns Promise<RailDeckRouteExecutionCancellationResponse>.

Example evidence: Retained SDK transport fixture.

routes.get

Opens the original selected saved route without claiming it confirms a write.

const result = await client.routes.get(
  "1",
  "1",
  "1",
  {}
);

TypeScript parameters and return type

accountId · required: string
Owning account.
layoutId · required: string
Original layout.
routeId · required: string
Selected route.
options · optional: RailDeckRequestControlOptions
Cancellation/deadline.

Returns Promise<RouteRecord>.

Example evidence: Retained SDK transport fixture.

routes.create

Captures the complete original creation before authentication can yield.

const result = await client.routes.create(
  "23",
  "31",
  {
    "requestId": "aabbccdd-aabb-4abb-8abb-aabbccddeeff",
    "definition": {
      "displayName": "{{fixtureDisplayName}}",
      "description": "Use the reception road.\n\nThe yard lamps are separate.",
      "enabled": true,
      "metadata": {
        "raildeckPicture": {
          "photographId": null,
          "symbol": "night"
        },
        "retained": {
          "label": "Existing route information"
        }
      },
      "steps": [
        {
          "accessoryId": "91",
          "targetState": "thrown",
          "sequenceOrder": 1,
          "delayMs": 0,
          "metadata": {
            "purpose": "Reception road"
          }
        },
        {
          "accessoryId": "92",
          "targetState": "on",
          "sequenceOrder": 2,
          "delayMs": 250,
          "metadata": {}
        }
      ]
    }
  },
  {}
);

TypeScript parameters and return type

accountId · required: string
Owning account.
layoutId · required: string
Original layout.
input · required: CreateRouteCommand
Original request identity and complete draft.
options · optional: RailDeckRequestControlOptions
Request lifetime; interrupted confirmation remains uncertain.

Returns Promise<RouteMutationReceipt>.

Example evidence: Retained SDK transport fixture.

routes.update

Replaces only the reviewed complete definition, not a partial unreviewed draft.

const result = await client.routes.update(
  "1",
  "1",
  "1",
  {
    "requestId": "c8821c01-eb90-4324-9079-c83d76ba8444",
    "expectedRevision": 2,
    "definition": {
      "displayName": "{{fixtureDisplayName}}",
      "description": null,
      "enabled": true,
      "metadata": {},
      "steps": [
        {
          "accessoryId": "1",
          "targetState": "closed",
          "sequenceOrder": 1,
          "delayMs": 0,
          "metadata": {}
        },
        {
          "accessoryId": "3",
          "targetState": "on",
          "sequenceOrder": 2,
          "delayMs": 0,
          "metadata": {}
        },
        {
          "accessoryId": "2",
          "targetState": "green",
          "sequenceOrder": 3,
          "delayMs": 0,
          "metadata": {}
        }
      ]
    }
  },
  {}
);

TypeScript parameters and return type

accountId · required: string
Owning account.
layoutId · required: string
Original layout.
routeId · required: string
Reviewed route.
input · required: UpdateRouteCommand
Complete original replacement and reviewed revision.
options · optional: RailDeckRequestControlOptions
Request lifetime without automatic replay.

Returns Promise<RouteMutationReceipt>.

Example evidence: Retained SDK transport fixture.

routes.delete

Removes the deliberately reviewed route and retains its original retry evidence.

const result = await client.routes.delete(
  "23",
  "31",
  "12",
  {
    "requestId": "aabbccdd-aabb-4abb-8abb-aabbccddeeff",
    "expectedRevision": 10
  },
  {}
);

TypeScript parameters and return type

accountId · required: string
Owning account.
layoutId · required: string
Original layout.
routeId · required: string
Reviewed route.
input · required: DeleteRouteCommand
Original removal identity and reviewed revision.
options · optional: RailDeckRequestControlOptions
Cancellation/deadline, not proof of remote rollback.

Returns Promise<RouteMutationReceipt>.

Example evidence: Retained SDK transport fixture.

routes.saveOrder

Saves the complete reviewed layout-wide order without changing configuration.

const result = await client.routes.saveOrder(
  "23",
  "31",
  {
    "requestId": "aabbccdd-aabb-4abb-8abb-aabbccddeeff",
    "reviewedIds": [
      "12",
      "13"
    ],
    "orderedIds": [
      "13",
      "12"
    ]
  },
  {}
);

TypeScript parameters and return type

accountId · required: string
Owning account.
layoutId · required: string
Original layout.
input · required: ReviewedOrderCommand
Original reviewed permutation.
options · optional: RailDeckRequestControlOptions
Request lifetime without polling or automatic retries.

Returns Promise<ReviewedOrderReceipt>.

Example evidence: Retained SDK transport fixture.

Download all TypeScript method examples

JavaScript calls and TypeScript downloads are checked through the real SDK using local response fixtures. This verifies the calls and decoding for those fixtures.

Handle errors and uncertain outcomes

Choose another feature

The complete TypeScript workflow

Follow how the calls fit together, including the review and recovery steps. Supply your configured client and explicitly selected development records. Importing the download performs no requests; mutations are never retried automatically.

import type { RailDeckDirectIntegrationClient as Client } from '@raildeck/frontend-sdk/direct-integration';

/**
 * Read the selected route and analyse its current activation consequences.
 * @param client - Configured client; the caller owns current authority.
 * @param accountId - Authorised account for this workflow.
 * @param layoutId - Explicitly selected layout within the account.
 * @param routeId - Saved route chosen for review.
 * @param signal - Caller-owned cancellation signal.
 * @returns A definition and advisory analysis for an explicit operator decision.
 */
export async function prepareRouteActivation(
  client: Client,
  accountId: string,
  layoutId: string,
  routeId: string,
  signal: AbortSignal,
) {
  const options = { signal, timeoutMs: 15_000 };
  const route = await client.routes.get(accountId, layoutId, routeId, options);
  const analysis = await client.routes.analyseActivation(accountId, layoutId, routeId);
  return { route, analysis };
}

/**
 * Submit the original activation intent only after its explicit confirmation.
 * @param client - Configured client; the caller owns current authority.
 * @param accountId - Authorised account for this workflow.
 * @param layoutId - Explicitly selected layout within the account.
 * @param routeId - Saved route chosen for review.
 * @param reviewed - Original reviewed command, including its request identity and revision.
 * @param signal - Caller-owned cancellation signal.
 * @returns The correlated receipt; no automatic retry, fresh revision or replacement intent.
 */
export async function activateReviewedRoute(
  client: Client,
  accountId: string,
  layoutId: string,
  routeId: string,
  reviewed: Parameters<Client['routes']['activate']>[3],
  signal: AbortSignal,
) {
  return client.routes.activate(accountId, layoutId, routeId, reviewed, {
    signal, timeoutMs: 15_000,
  });
}

Download TypeScript example

How the calls fit together

JavaScript examples

The complete TypeScript workflow

Related information