Pictures and media

Manage media assets, approved uploads and links to railway items.

Source 0.1.0 Private source package

How the calls fit together

Reserve an upload, transfer the file using the returned upload instructions, complete verification and then link the ready asset. Never publish signed upload URLs.

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

media.completeUpload

Verifies a reserved private R2 upload before it can be linked.

const result = await client.media.completeUpload(
  "23",
  "3",
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Owning account.
mediaAssetId · required: RailDeckIdentifier
Reserved upload.
options · optional: RailDeckRequestControlOptions
Cancellation.

Returns Promise<RailDeckMediaAsset>.

Example evidence: Retained SDK transport fixture.

media.listAssets

Lists media assets owned by an account.

const result = await client.media.listAssets(
  "account 1"
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the media assets.

Returns Promise<RailDeckMediaAssetListResponse>.

Example evidence: Retained SDK transport fixture.

media.createAsset

Creates one account media asset record after an upload has completed.

const result = await client.media.createAsset(
  "account 1",
  {
    "provider": "cloudflare_images",
    "providerAssetId": "cloudflare-image-1",
    "mediaType": "image",
    "displayName": "{{fixtureDisplayName}}",
    "altText": "Mallard at the platform",
    "originalUrl": "https://imagedelivery.net/rail/media-2/public",
    "variants": {
      "dial": "https://imagedelivery.net/rail/media-2/dial"
    },
    "width": 1600,
    "height": 900,
    "metadata": {
      "source": "demo-upload"
    }
  },
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that will own the media asset.
input · required: CreateRailDeckMediaAssetInput
Provider asset id, public URL, variants, dimensions, and metadata.
options · optional: RailDeckRequestControlOptions
Optional request cancellation controls.

Returns Promise<RailDeckMediaAsset>.

Example evidence: Retained SDK transport fixture.

media.getAsset

Loads one account media asset.

const result = await client.media.getAsset(
  "account 1",
  "media-2",
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the media asset.
mediaAssetId · required: RailDeckIdentifier
Media asset to load.
options · optional: RailDeckRequestControlOptions
Optional request cancellation controls.

Returns Promise<RailDeckMediaAsset>.

Example evidence: Retained SDK transport fixture.

media.updateAsset

Updates one account media asset.

const result = await client.media.updateAsset(
  "account 1",
  "media-2",
  {
    "displayName": "{{fixtureDisplayName}}"
  }
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the media asset.
mediaAssetId · required: RailDeckIdentifier
Media asset to update.
input · required: UpdateRailDeckMediaAssetInput
Partial media asset update.

Returns Promise<RailDeckMediaAsset>.

Example evidence: Retained SDK transport fixture.

media.deleteAsset

Requests deletion for one account media asset.

const result = await client.media.deleteAsset(
  "account 1",
  "media-2"
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the media asset.
mediaAssetId · required: RailDeckIdentifier
Media asset to delete.

Returns Promise<RailDeckMediaAsset>.

Example evidence: Retained SDK transport fixture.

media.createUploadIntent

Creates a provider direct-upload intent for browser-side file uploads.

const result = await client.media.createUploadIntent(
  "account 1",
  {
    "provider": "cloudflare_images",
    "displayName": "{{fixtureDisplayName}}",
    "metadata": {
      "targetType": "locomotive"
    }
  },
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that will own the uploaded media.
input · required: CreateRailDeckMediaUploadIntentInput
Upload provider, display name, expiry, and safe metadata.
options · optional: RailDeckRequestControlOptions
Optional request cancellation controls.

Returns Promise<RailDeckMediaUploadIntent>.

Example evidence: Retained SDK transport fixture.

media.listLinks

Lists media links for one account-owned target entity.

const result = await client.media.listLinks(
  "account 1",
  {
    "targetType": "locomotive",
    "targetId": "loco-1"
  },
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the linked entity.
target · required: RailDeckMediaLinkTarget
Target type and id to list media links for.
options · optional: RailDeckRequestControlOptions
Optional request cancellation controls.

Returns Promise<RailDeckMediaLinkListResponse>.

Example evidence: Retained SDK transport fixture.

media.createLink

Links one media asset to a layout, locomotive, accessory, route, linked accessory, or rolling stock.

const result = await client.media.createLink(
  "account 1",
  {
    "targetType": "locomotive",
    "targetId": "loco-1",
    "mediaAssetId": "media-2",
    "role": "primary",
    "displayOrder": 1
  },
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the target and media asset.
input · required: CreateRailDeckMediaLinkInput
Target, media asset id, role, ordering, and metadata.
options · optional: RailDeckRequestControlOptions
Optional request cancellation controls.

Returns Promise<RailDeckMediaLink>.

Example evidence: Retained SDK transport fixture.

media.updateLink

Updates one media link.

const result = await client.media.updateLink(
  "account 1",
  "media-link-2",
  {
    "role": "gallery",
    "displayOrder": 2
  },
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the media link.
mediaLinkId · required: RailDeckIdentifier
Media link to update.
input · required: UpdateRailDeckMediaLinkInput
Partial role, display order, or metadata update.
options · optional: RailDeckRequestControlOptions
Optional request cancellation controls.

Returns Promise<RailDeckMediaLink>.

Example evidence: Retained SDK transport fixture.

media.deleteLink

Deletes one media link without deleting the underlying media asset.

const result = await client.media.deleteLink(
  "account 1",
  "media-link-2",
  {}
);

TypeScript parameters and return type

accountId · required: RailDeckIdentifier
Account that owns the media link.
mediaLinkId · required: RailDeckIdentifier
Media link to delete.
options · optional: RailDeckRequestControlOptions & { deleteUnreferencedAsset?: boolean }
Cancellation and optional deletion of an asset with no remaining links.

Returns Promise<RailDeckSuccessResponse>.

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';

/**
 * Inspect an uploaded asset and existing links before a separate link decision.
 * @param client - Configured client; the caller owns current authority.
 * @param accountId - Authorised account for this workflow.
 * @param assetId - Media asset reserved for this account.
 * @param target - Shortcut target explicitly selected by the person.
 * @param signal - Caller-owned cancellation signal.
 * @returns Asset processing status and links; wait for upload verification before confirming a link.
 */
export async function reviewMediaBeforeLinking(
  client: Client,
  accountId: string,
  assetId: string,
  target: Parameters<Client['media']['listLinks']>[1],
  signal: AbortSignal,
) {
  const options = { signal, timeoutMs: 15_000 };
  const asset = await client.media.getAsset(accountId, assetId, options);
  const links = await client.media.listLinks(accountId, target, options);
  return { asset, links };
}

/**
 * Create only the media link explicitly confirmed after asset review.
 * @param client - Configured client; the caller owns current authority.
 * @param accountId - Authorised account for this workflow.
 * @param input - Reviewed input for this operation.
 * @param signal - Caller-owned cancellation signal.
 * @returns The saved association; upload URLs and authority must remain private.
 */
export async function linkReviewedMedia(
  client: Client,
  accountId: string,
  input: Parameters<Client['media']['createLink']>[1],
  signal: AbortSignal,
) {
  return client.media.createLink(accountId, input, { signal, timeoutMs: 15_000 });
}

Download TypeScript example

How the calls fit together

JavaScript examples

The complete TypeScript workflow

Related information