Skip to main content
Rail Deck

Rail Deck is being prepared for an invitation-only Alpha. Check current availability

Developer documentation

Run a complete starter integration

Explore a complete SDK integration in an optional Node.js terminal project.

Source 0.1.0 Private source package

What is the Node starter?

It is a downloadable example application for your own computer. Node runs JavaScript outside the browser; this project uses TypeScript for type checking. Terminal choices, fictional API replies and automated tests show how individual calls become a complete integration.

Start with the short JavaScript examples if you only need a call. Choose this project when you want to explore account selection, saved-train edits, version conflicts or a lost reply. Node is required to run this starter, not to call the HTTP API.

See the pieces working together

Start with fictional railway data. The real SDK reads your fixture identity, lets you choose an account and layout, and decodes a scoped snapshot. You can then review one light change, confirm it explicitly and enquire about the original command after its reply is lost.

Fixtures run entirely locally. They demonstrate request and recovery behaviour; software acknowledgement does not establish that a physical accessory moved.

Use the authorised source checkout

You need Node.js 24.20.0, authorised access to the source SDK 0.1.0 at checkpoint 45e84479, and the repository’s pinned dependencies. The download contains the starter source, tests and README. The private SDK is not bundled or available through a public npm install.

Hosted SDK distribution is planned, but its infrastructure is not available yet. This source-checkout route is for authorised contributors. The download contains integration examples and fictional responses, not the Rail Deck backend or a running Rail Deck server.

Live mode uses the same selection and state owners with an approved development service and current token. It offers scoped reads and recovery of a known original command. Identity acquisition and refresh belong to your approved integration adapter.

Choose the level of detail you need

For an individual call, start with the JavaScript examples. The TypeScript workflows connect related calls. This Node starter adds terminal choices, local response fixtures and tests around a complete journey. You can use the examples without adopting its structure.

Download and run

Download starter project (.tgz)

Extract it inside your authorised checkout so it can use the private SDK and pinned tools. Follow the included README; no credentials are needed for fixtures.

Start the local project

mkdir -p examples/community-starter
tar -xzf /path/to/rail-deck-community-starter-0.1.0.tgz --strip-components=1 -C examples/community-starter
cd examples/community-starter
npm run check
npm test
npm start

Follow one complete journey

  1. Choose account 1, Starter account, then layout 1, Branch line.
  2. Choose s to review the fictional light change. Check the displayed scope, target and revision.
  3. Type the exact send phrase shown, including its command ID. The default fixture loses the reply.
  4. Choose c to recover that original command and read a fresh snapshot. No command is replayed.
  5. Choose q to close. Restart for another operating exercise.

Try npm start -- --scenario accepted, pending, unavailable, forbidden or mfa-required to explore other outcomes. A pending or unknown command keeps its original identity and blocks a replacement.

Edit a saved train and resolve a conflict

Run npm start -- --scenario train-conflict. Choose account 1 and layout 1, then t for saved trains and train 1, Branch passenger. Trains belong to the account; this list is independent of layout assignment.

  1. Choose e, then 4 for Freight. Only the local style draft changes.

  2. Choose v, review the train, style, handling and revision, then type the displayed save phrase. The first save meets a version conflict. Your draft stays available.

  3. Choose l to reload. Compare the newer Express passenger style and Automatic handling with your retained Freight draft.

  4. Choose v again and confirm the new revision. This distinct save preserves the newer handling.

Try train-conflict-again, train-refused or train-lost-response for other outcomes. Back returns to the main menu with the draft retained. A lost reply never causes an automatic retry. Live saved-train views are read-only.

The download reuses the saved-train workflow. It edits driving style; formation, handling edits and current runs keep their existing owners.

How the starter is organised

  • main.ts connects console input, cancellation and cleanup.
  • configuration.ts and authority.ts own mode and current-token lifetime.
  • selection.ts owns explicit account/layout choices and rejects late responses from retired selections.
  • accessory-command.ts owns immutable review, one send and original-command recovery.
  • saved-train.ts owns saved revision, draft, conflict recovery and fresh review.
  • fixture-transport.ts checks real SDK requests and supplies typed fictional replies.
  • cli.ts presents choices and distinguishes acceptance, uncertainty and observation.

The project reuses the published scoped read example and command recovery workflow. Its tests cover cancellation, stale scope, confirmation, lost replies and process output.

How the SDK is connected

This is the exact runtime module in the download. Both modes use the real SDK; fixtures inject a closed local transport.

import {
  createRailDeckDirectIntegrationClient,
  type RailDeckAccessTokenProvider,
  type RailDeckDirectIntegrationClient,
} from '@raildeck/frontend-sdk/direct-integration';
import type { StarterSettings } from './configuration.js';
import { fixtureChange } from './fixture-data.js';
import { StarterFixtureTransport } from './fixture-transport.js';
import { StarterProblem } from './problems.js';

/** The CLI's operating exercise exists only in its closed fixture runtime. */
export type StarterRuntime =
  | Readonly<{ kind: 'fixtures'; client: RailDeckDirectIntegrationClient;
      transport: StarterFixtureTransport; change: typeof fixtureChange }>
  | Readonly<{ kind: 'live'; client: RailDeckDirectIntegrationClient }>;

/**
 * Assemble one actual SDK client, changing only the external transport boundary for fixtures.
 * @param settings - Validated runtime choice.
 * @param getAccessToken - Live identity adapter; fixture mode ignores this argument entirely.
 * @returns The configured runtime, with no request on construction.
 */
export function createStarterRuntime(
  settings: Exclude<StarterSettings, { kind: 'help' }>,
  getAccessToken?: RailDeckAccessTokenProvider,
): StarterRuntime {
  if (settings.kind === 'fixtures') {
    const transport = new StarterFixtureTransport(settings.scenario);
    return { kind: 'fixtures', transport, change: fixtureChange,
      client: createRailDeckDirectIntegrationClient({
        baseUrl: 'https://api.raildeck.test', fetch: transport.fetch, timeoutMs: 15_000,
        /** @returns A deliberately non-secret fixture value, never live authority. */
        getAccessToken: () => 'starter-fixture',
      }) };
  }
  if (getAccessToken === undefined) throw new StarterProblem('Provide your approved identity adapter.');
  return { kind: 'live', client: createRailDeckDirectIntegrationClient({
    baseUrl: settings.baseUrl, getAccessToken, timeoutMs: 15_000,
  }) };
}

Move to approved development reads

Follow the README’s approved API and current-token setup, then run npm run live. Extend the token adapter with your approved identity lifecycle. Retain uncertain command IDs before closing: the starter keeps no durable command journal.

Continue with authentication or choose another feature workflow.

Related information

Information reviewed .