The App SDK Reference

The App SDK Reference

The @datamagik/app-sdk package is the typed bridge between your custom Vue app and the platform. It is the only way a SPA app reaches data, scripts, serials, and printers — and every call is authorized server-side against your app's declared resources.

Install & import

npm install @datamagik/app-sdk

// Prefer the generated, fully-typed entry (aliases autocomplete):
import { dm } from './dm.generated';

src/dm.generated.ts is produced by dm typegen from your dm.config.json. Commit it.

Initialize & context

await dm.init();          // resolves the platform context; call once at startup
dm.context;               // the resolved context
dm.context.params;        // screen-context params (e.g. order id) — same on web, Plex, mobile

Data

const rows = await dm.data.query('parts');            // alias autocompletes; rows are typed
const rows2 = await dm.data.query('openOrders', opts); // optional query options

Scripts

const out = await dm.scripts.run('postReceipt', { poNumber: 'PO-1', quantity: 5 });

The platform stores no schema for scripts, so script IO defaults to unknown. Type a script by augmenting DmScriptTypes (declaration merging) — for example in src/dm-script-types.d.ts:

declare module '@datamagik/app-sdk' {
  interface DmScriptTypes {
    postReceipt: {
      inputs: { poNumber: string; quantity: number };
      output: { ok: boolean; receiptId: number };
    };
  }
}
export {};

Now dm.scripts.run('postReceipt', ...) is fully typed. Unaugmented scripts stay { inputs?: Record<string, unknown>; output: unknown }.

Serial numbers

const preview = await dm.serials.preview('lotSerial', { PART: 'P-100' });
const sn      = await dm.serials.generate('lotSerial', { PART: 'P-100' });

Printing

const printers = await dm.printers.list();
await dm.print.submit('line1Zebra', { format: 'zpl', data: label });

Navigation & output events

dm.navigate(target);                                  // move to another app/screen
dm.emitOutput('completed', { received: rows.length }); // tell the host something happened
dm.on('app-output', handler);                          // observe output events

How transports work

• In production the app runs in a sandboxed iframe and the SDK speaks a postMessage bridge (correlation ids, 60s timeouts). The dm.init() handshake re-sends dm-ready until the host answers.
• Under dm dev there is no host page; the SDK falls back to a dev proxy that maps bridge calls to /api/... fetches, proxied to the platform with your builder bearer.

Selection is automatic in dm.init() — you write the same code for both.

v1 limitations

dm.data.writeRow and dm.capture.* are not part of the v1 SPA surface. Reading lookup data, running scripts, generating serials, and printing are fully supported. See Custom Vue SPA Apps.