TypeScript

To create or join a space in ECHO, the user must first establish a HALO identity. This can be done by creating a new identity or accepting a device join invitation.

Obtaining identity

import { Client } from '@dxos/client';

const client = new Client();

(async () => {
  await client.initialize();
  const identity = client.halo.identity.get();
})();

The object returned is of type Identity.

Creating an identity

Create a new identity:

import { Client } from '@dxos/client';

const client = new Client();

(async () => {
  await client.initialize();
  const identity = await client.halo.createIdentity();
})();

Creating an identity with a display name

Pass displayName to createProfile:

import { Client } from '@dxos/client';

const client = new Client();

(async () => {
  await client.initialize();
  const identity = await client.halo.createIdentity({
    displayName: 'Alice',
  });
})();

Before data can be manipulated, a space must be obtained.

Receiving a device join invitation

We often want to add a device to the same HALO identity. You can accept a device join invitation by providing the invitation code and the auth code to the dxos client. This example demonstrates how to accept a device join invitation in a console application. A device join invitation can be obtained from the shell or generated in typescript from an existing identity.

import { type Client } from '@dxos/client';
import { InvitationEncoder } from '@dxos/client-protocol';

/** Accepts a device join invitation by prompting the user for:
 *    - invitation code
 *    - authentication code */
const acceptInvitation = async (
  client: Client,
  deviceInvitationCode: string,
) => {
  const decodedInvitation = InvitationEncoder.decode(deviceInvitationCode);
  const invitationResult = client.halo.join(decodedInvitation);

  if (decodedInvitation.authCode) {
    await invitationResult.authenticate(decodedInvitation.authCode);
  } else {
    const authCode = '123456'; // Take this as input from the user.
    await invitationResult.authenticate(authCode);
  }
};

Tips

• Your client instance needs to be configured correctly to talk to a signaling service.
• If accepting a device join invitation from a UI application using the shell (e.g. Composer), you will only be presented with the authCode after the call to halo.join has been made.

Retrieving a device invitation code from an invitation URL

/** Extracts device invitation code from a URL or string. */
const extractDeviceInvitationCode = (encoded: string) => {
  if (encoded.startsWith('http')) {
    const searchParams = new URLSearchParams(
      encoded.substring(encoded.lastIndexOf('?')),
    );

    return searchParams.get('deviceInvitationCode') ?? null;
  }

  return encoded;
};