Quick start — Voke ESM

mkdir voke-esm-quickstart && cd voke-esm-quickstart
bun init
bun add amqplib
bun add -d @types/amqplib tsx typescript

// amqp-connect.ts
// Connect to Voke's RabbitMQ using the AMQPS URI from the Connect partner wizard.
// The URI shape is:
//   amqps://{org-slug}:{url-encoded-key}@mqtt.voke.lovinka.com:5671/partner-{keyId}
import * as amqp from 'amqplib';

export interface VokeAmqpCreds {
  /**
   * The full AMQPS URI from the Connections reveal screen.
   * Contains org slug (username), raw API key (password), host, port, and
   * per-key vhost (`partner-{keyId}`) — no manual assembly required.
   */
  amqpsUri: string;
  /** Your organization slug — used for queue/routing-key prefixes only. */
  orgSlug: string;
}

export async function connectVoke(creds: VokeAmqpCreds) {
  const conn = await amqp.connect(creds.amqpsUri);
  const ch = await conn.createChannel();
  const prefix = `vcp.${creds.orgSlug}`;

  // Queues are asserted (and bound to the `vcp` exchange) by Voke when
  // trading is enabled for your org. checkQueue verifies they exist before
  // any publish or consume.
  const inbound = {
    commands: `${prefix}.command`,
    config: `${prefix}.config`,
    schedule: `${prefix}.schedule`,
  };
  const outbound = {
    telemetry: `${prefix}.event.telemetry`,
    status: `${prefix}.event.status`,
    alarm: `${prefix}.event.alarm`,
    execution: `${prefix}.event.execution`,
  };

  for (const q of [...Object.values(inbound), ...Object.values(outbound)]) {
    await ch.checkQueue(q);
  }

  return { conn, ch, exchange: 'vcp', prefix, inbound, outbound };
}

// run-connect.ts
import { connectVoke } from './amqp-connect';

(async () => {
  const { conn, inbound, outbound } = await connectVoke({
    // Paste the AMQPS URI from the Connections reveal screen.
    amqpsUri: 'amqps://YOUR-ORG-SLUG:URL-ENCODED-KEY@mqtt.voke.lovinka.com:5671/partner-XXXX',
    orgSlug: 'YOUR-ORG-SLUG',
  });
  console.log('inbound queues OK:', inbound);
  console.log('outbound queues OK:', outbound);
  await conn.close();
})();

npx tsx run-connect.ts
# Expected:
# inbound queues OK: { commands: 'vcp.acme.command', config: 'vcp.acme.config', schedule: 'vcp.acme.schedule' }
# outbound queues OK: { telemetry: 'vcp.acme.event.telemetry', status: 'vcp.acme.event.status', ... }

// publish-command.ts
// Publish a VCP command by routing it through the `vcp` exchange.
import { randomUUID } from 'node:crypto';
import { connectVoke, type VokeAmqpCreds } from './amqp-connect';

export interface VcpCommandInput {
  commandType: string;             // e.g. 'site-setpoint', 'mode-change'
  siteId: string;                  // target Voke site / plant identifier
  source: string;                  // your partner ID (e.g. 'obzor')
  payload: Record<string, unknown>; // shape depends on commandType
  correlationId?: string;          // echoed back in event.status for correlation
}

export async function publishCommand(creds: VokeAmqpCreds, input: VcpCommandInput) {
  const { ch, exchange, conn } = await connectVoke(creds);

  const envelope = {
    version: '1.1' as const,
    messageId: randomUUID(),
    correlationId: input.correlationId,
    timestamp: new Date().toISOString(),
    source: input.source,
    siteId: input.siteId,
    payload: input.payload,
  };

  const routingKey = `${creds.orgSlug}.command.${input.commandType}`;
  ch.publish(exchange, routingKey, Buffer.from(JSON.stringify(envelope)), {
    contentType: 'application/json',
    persistent: true,
    messageId: envelope.messageId,
    correlationId: envelope.correlationId,
    timestamp: Date.parse(envelope.timestamp),
  });

  await ch.close();
  await conn.close();
}

// run-publish.ts
import { publishCommand } from './publish-command';

(async () => {
  await publishCommand(
    {
      amqpsUri: 'amqps://YOUR-ORG-SLUG:URL-ENCODED-KEY@mqtt.voke.lovinka.com:5671/partner-XXXX',
      orgSlug: 'YOUR-ORG-SLUG',
    },
    {
      commandType: 'site-setpoint',
      siteId: 'YOUR-FAKE-PLANT-EXTERNAL-ID',
      source: 'YOUR-PARTNER-ID',
      payload: {
        type: 'POWER',
        targetValueKw: 10,
        direction: 'EXPORT',
        includeConsumption: true,
        priority: 'NORMAL',
        validFrom: new Date().toISOString(),
      },
    },
  );
  console.log('command published');
})();

npx tsx run-publish.ts
# Expected: command published

// consume-telemetry.ts
// Subscribe to telemetry events emitted by Voke on your org's outbound
// event.telemetry queue.
import { connectVoke, type VokeAmqpCreds } from './amqp-connect';

export interface VcpEnvelope<T = unknown> {
  version: '1.1';
  messageId: string;
  correlationId?: string;
  timestamp: string;
  source: string;
  siteId: string;
  payload: T;
}

export async function consumeTelemetry(
  creds: VokeAmqpCreds,
  onMessage: (envelope: VcpEnvelope) => void,
) {
  const { ch, outbound } = await connectVoke(creds);
  await ch.consume(outbound.telemetry, (msg) => {
    if (!msg) return;
    try {
      const envelope = JSON.parse(msg.content.toString()) as VcpEnvelope;
      onMessage(envelope);
      ch.ack(msg);
    } catch {
      // Malformed payload — dead-letter rather than redeliver.
      ch.nack(msg, false, false);
    }
  });
}

// run-consume.ts
import { consumeTelemetry } from './consume-telemetry';

(async () => {
  console.log('Listening for telemetry for 30 seconds...');
  await consumeTelemetry(
    {
      amqpsUri: 'amqps://YOUR-ORG-SLUG:URL-ENCODED-KEY@mqtt.voke.lovinka.com:5671/partner-XXXX',
      orgSlug: 'YOUR-ORG-SLUG',
    },
    (envelope) => {
      console.log('telemetry siteId:', envelope.siteId);
      console.log('telemetry payload:', JSON.stringify(envelope.payload, null, 2));
    },
  );
  await new Promise((resolve) => setTimeout(resolve, 30_000));
  process.exit(0);
})();

npx tsx run-consume.ts