Skip to content
Docs
Open Backstage
Reference

BackstageClient.deviceSelf

BackstageClient.deviceSelf in @ticketlayer/backstage.

@ticketlayer/backstage

@ticketlayer/backstage / BackstageClient / deviceSelf

deviceSelf: {
  declarePeripherals: (request: {
     peripherals: {
        address?: {
           host: string;
           port: number;
        };
        attachment?: "child" | "routed";
        capabilities?: Record<string, any>;
        clientKey: string;
        kind: string;
        model?: string;
        name: string;
        provider?: string;
        vendor?: string;
     }[];
   }, requestOptions?: RequestOptions) => Promise<{
     clientKey: string;
     deviceId: string;
  }[]>;
  fetchCommands: (options?: {
     wait?: number;
   }, requestOptions?: RequestOptions) => Promise<{
     createdAt: string;
     expiresAt: string;
     id: string;
     payload: {
      [key: string]: unknown;
     };
     peripheralId: string | null;
     type: string;
  }[]>;
  getCertificate: (requestOptions?: RequestOptions) => Promise<{
     certPem: string;
     hostname: string;
     notAfter: string;
     privateKeyPem: string;
  }>;
  getMe: (requestOptions?: RequestOptions) => Promise<{
     config: {
        corsAllowlist: string[];
        localHostname: string | null;
     };
     device: {
        accountId: string;
        id: string;
        location:   | {
           id: string;
           name: string;
         }
           | null;
        name: string;
        organisationId: string;
        type: string;
     };
     roles: {
        accountId: string;
        roleId: string;
     }[];
  }>;
  heartbeat: (request: {
     appVersion?: string;
     lanAddresses?: {
        interface: string;
        ip: string;
     }[];
     localPort?: number;
     peripheralStatuses?: {
        clientKey: string;
        status: Record<string, any>;
     }[];
   }, requestOptions?: RequestOptions) => Promise<{
     certificateRenewalDue: boolean;
     commandsPending: number;
     jwksVersion: number;
     serverTime: string;
  }>;
  ingestEvents: (request: {
     events: {
        id: string;
        occurredAt: string;
        payload?: Record<string, any>;
        type: string;
     }[];
   }, requestOptions?: RequestOptions) => Promise<{
     id: string;
     outcome: "duplicate" | "accepted";
  }[]>;
  reportProgress: (commandId: string, request: {
     progress: Record<string, any>;
  }, requestOptions?: RequestOptions) => Promise<boolean>;
  reportResult: (commandId: string, request: {
     result?: Record<string, any>;
     status: "failed" | "completed";
  }, requestOptions?: RequestOptions) => Promise<string>;
};

Defined in: client.ts:9713

Device Self methods

declarePeripherals()#

declarePeripherals: (request: {
  peripherals: {
     address?: {
        host: string;
        port: number;
     };
     attachment?: "child" | "routed";
     capabilities?: Record<string, any>;
     clientKey: string;
     kind: string;
     model?: string;
     name: string;
     provider?: string;
     vendor?: string;
  }[];
}, requestOptions?: RequestOptions) => Promise<{
  clientKey: string;
  deviceId: string;
}[]>;

Declare peripherals Full-replacement declaration of the relay’s peripherals; returns the stable device id per clientKey.

Parameters#

ParameterType
request{ peripherals: { address?: { host: string; port: number; }; attachment?: "child" | "routed"; capabilities?: Record<string, any>; clientKey: string; kind: string; model?: string; name: string; provider?: string; vendor?: string; }[]; }
request.peripherals{ address?: { host: string; port: number; }; attachment?: "child" | "routed"; capabilities?: Record<string, any>; clientKey: string; kind: string; model?: string; name: string; provider?: string; vendor?: string; }[]
requestOptions?RequestOptions

Returns#

Promise<{ clientKey: string; deviceId: string; }[]>

Operation Id#

declareDevicePeripherals

fetchCommands()#

fetchCommands: (options?: {
  wait?: number;
}, requestOptions?: RequestOptions) => Promise<{
  createdAt: string;
  expiresAt: string;
  id: string;
  payload: {
   [key: string]: unknown;
  };
  peripheralId: string | null;
  type: string;
}[]>;

Long-poll for commands Holds up to wait seconds (max 25) and returns pending commands, marking them delivered.

Parameters#

ParameterType
options?{ wait?: number; }
options.wait?number
requestOptions?RequestOptions

Returns#

Promise<{ createdAt: string; expiresAt: string; id: string; payload: { [key: string]: unknown; }; peripheralId: string | null; type: string; }[]>

Operation Id#

fetchDeviceCommands

getCertificate()#

getCertificate: (requestOptions?: RequestOptions) => Promise<{
  certPem: string;
  hostname: string;
  notAfter: string;
  privateKeyPem: string;
}>;

Get local TLS certificate Fetch (or trigger issuance of) the device’s local-control-plane TLS cert + key.

Parameters#

ParameterType
requestOptions?RequestOptions

Returns#

Promise<{ certPem: string; hostname: string; notAfter: string; privateKeyPem: string; }>

Operation Id#

getDeviceCertificate

getMe()#

getMe: (requestOptions?: RequestOptions) => Promise<{
  config: {
     corsAllowlist: string[];
     localHostname: string | null;
  };
  device: {
     accountId: string;
     id: string;
     location:   | {
        id: string;
        name: string;
      }
        | null;
     name: string;
     organisationId: string;
     type: string;
  };
  roles: {
     accountId: string;
     roleId: string;
  }[];
}>;

Get own device record The device fetches its own record, granted roles and local config (device JWT).

Parameters#

ParameterType
requestOptions?RequestOptions

Returns#

Promise<{ config: { corsAllowlist: string[]; localHostname: string | null; }; device: { accountId: string; id: string; location: | { id: string; name: string; } | null; name: string; organisationId: string; type: string; }; roles: { accountId: string; roleId: string; }[]; }>

Operation Id#

getDeviceMe

heartbeat()#

heartbeat: (request: {
  appVersion?: string;
  lanAddresses?: {
     interface: string;
     ip: string;
  }[];
  localPort?: number;
  peripheralStatuses?: {
     clientKey: string;
     status: Record<string, any>;
  }[];
}, requestOptions?: RequestOptions) => Promise<{
  certificateRenewalDue: boolean;
  commandsPending: number;
  jwksVersion: number;
  serverTime: string;
}>;

Send a device heartbeat Reports presence + peripheral status; returns hints (commandsPending, cert renewal, JWKS version).

Parameters#

ParameterType
request{ appVersion?: string; lanAddresses?: { interface: string; ip: string; }[]; localPort?: number; peripheralStatuses?: { clientKey: string; status: Record<string, any>; }[]; }
request.appVersion?string
request.lanAddresses?{ interface: string; ip: string; }[]
request.localPort?number
request.peripheralStatuses?{ clientKey: string; status: Record<string, any>; }[]
requestOptions?RequestOptions

Returns#

Promise<{ certificateRenewalDue: boolean; commandsPending: number; jwksVersion: number; serverTime: string; }>

Operation Id#

deviceHeartbeat

ingestEvents()#

ingestEvents: (request: {
  events: {
     id: string;
     occurredAt: string;
     payload?: Record<string, any>;
     type: string;
  }[];
}, requestOptions?: RequestOptions) => Promise<{
  id: string;
  outcome: "duplicate" | "accepted";
}[]>;

Upload device events Batch (≤500) idempotent upload of device-operational events; per-item accepted|duplicate.

Parameters#

ParameterType
request{ events: { id: string; occurredAt: string; payload?: Record<string, any>; type: string; }[]; }
request.events{ id: string; occurredAt: string; payload?: Record<string, any>; type: string; }[]
requestOptions?RequestOptions

Returns#

Promise<{ id: string; outcome: "duplicate" | "accepted"; }[]>

Operation Id#

ingestDeviceEvents

reportProgress()#

reportProgress: (commandId: string, request: {
  progress: Record<string, any>;
}, requestOptions?: RequestOptions) => Promise<boolean>;

Report command progress Optional in-flight progress update (e.g. payment terminal awaiting card).

Parameters#

ParameterType
commandIdstring
request{ progress: Record<string, any>; }
request.progressRecord<string, any>
requestOptions?RequestOptions

Returns#

Promise<boolean>

Operation Id#

reportCommandProgress

reportResult()#

reportResult: (commandId: string, request: {
  result?: Record<string, any>;
  status: "failed" | "completed";
}, requestOptions?: RequestOptions) => Promise<string>;

Report command result Terminal result (completed|failed). Idempotent - the first terminal result wins.

Parameters#

ParameterType
commandIdstring
request{ result?: Record<string, any>; status: "failed" | "completed"; }
request.result?Record<string, any>
request.status?"failed" | "completed"
requestOptions?RequestOptions

Returns#

Promise<string>

Operation Id#

reportCommandResult