Handle commands and uncertain outcomes
Distinguish request acceptance, command completion and unknown delivery before deciding what to do next.
Source 0.1.0 Private source package
Read the outcome you actually have
An accepted request is not evidence of completed physical movement. Preserve the original command identity and follow its documented result. Pending, rejected, failed and unknown outcomes need distinct presentation.
Narrow SDK errors
Use isRailDeckApiError before reading kind, errorCode, statusCode or correlationId. Transport kinds include network, timeout, aborted, decode and security as well as api. Never display raw details or assume every thrown value is an SDK error.
Respect retryAfterSeconds and the documented rate-limit policy. A timeout, disconnect or 503 does not prove that a mutation was absent. Do not blindly retry movement, route execution or other protected writes.
Handle an uncertain result
Use the feature’s documented recovery/readback path when it exists. Preserve supported idempotency keys and receipt fences. If the result remains unknown, tell the operator and require an explicit recovery decision; do not invent success or a replacement command.
Handle a refused or uncertain save
import { isRailDeckApiError, type RailDeckDirectIntegrationClient as Client } from '@raildeck/frontend-sdk/direct-integration';
type SaveInput = Parameters<Client['rollingStock']['update']>[2];
/**
* Submit one reviewed save and distinguish an SDK failure from an unexpected failure.
* @param client - Configured integration client with caller-owned authority.
* @param accountId - Account containing the selected vehicle.
* @param vehicleId - Vehicle whose version the person reviewed.
* @param input - Original save, including its expectedUpdatedAt concurrency fence.
* @returns A discriminated result; failures preserve the original intent without replay.
*/
export async function saveVehicleWithOutcome(
client: Client,
accountId: string,
vehicleId: string,
input: SaveInput,
) {
try {
const vehicle = await client.rollingStock.update(accountId, vehicleId, input);
return { kind: 'saved' as const, vehicle };
} catch (error: unknown) {
if (!isRailDeckApiError(error)) throw error;
return {
kind: 'needs-review' as const,
errorKind: error.kind,
errorCode: error.errorCode,
statusCode: error.statusCode,
correlationId: error.correlationId,
retryAfterSeconds: error.retryAfterSeconds,
};
}
}