TypeScript SDK Examples

Code examples for common operations using @idunion/tl-sdk.

Setup

Install the SDK and instantiate the client. The DefaultApi class accepts a Configuration object and an optional base path.

import { DefaultApi } from "@idunion/tl-sdk";

const tlClient = new DefaultApi(
  { isJsonMime: () => true },
  process.env.TL_API_URL,
);

All write operations require a bearer token passed via Axios request options. Read operations on public endpoints (e.g. fetching the ETSI XML) do not require authentication.

const authHeader = (token: string) => ({
  headers: { Authorization: `Bearer ${token}` },
});

---

Trust List Creation

Create a new Trust List by providing its name, description, the governance wallet, the verifier used for onboarding credential verification, and the list type.

import { DefaultApi, TlPayload, TlType } from "@idunion/tl-sdk";

const tlPayload: TlPayload = {
  name: "My Wallet Provider Trust List",
  description: "Trust List for certified wallet providers under the EUDIW framework",
  governanceWalletId: "wallet-abc123",   // wallet used for VC interactions
  verifierId: "verifier-xyz456",         // verifier that checks onboarding credentials
  type: TlType.WalletProvider,           // one of the TlType enum values
};

const { data: tl } = await tlClient.tlCreate(tlPayload, authHeader(token));

console.log("Created TL:", tl.id, tl.didBase);

Available TlType values:

Value	Description
TlType.WalletProvider	Wallet Provider
TlType.QeaaProvider	QEAA Provider
TlType.PuBeaaProvider	PuB-EAA Provider
TlType.EaaProvider	EAA Provider
TlType.PidProvider	PID Provider
TlType.AccessCertificateAuthority	Access Certificate Authority
TlType.RegistrationCertificatesProvider	Provider of Registration Certificates

---

Direct Onboarding

In the direct onboarding flow the Trust List operator creates a Trust List Record (TLR) on behalf of the applicant. The applicant provides a CSR and organisation details out-of-band; the operator submits them via tlrCreate.

import { DefaultApi, TlrCreatePayload } from "@idunion/tl-sdk";

const tlId = "my-trust-list-id";

const payload: TlrCreatePayload = {
  // applicant's Certificate Signing Request (PEM-encoded)
  csr: "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----",

  // organisation details
  orgName: "Example GmbH",
  orgTradeName: "Example",
  orgStreetAddress: "Musterstraße 1",
  orgCity: "Berlin",
  orgState: "Berlin",
  orgPostalCode: "10115",
  orgCountry: "DE",
  orgEmail: "contact@example.com",
  orgPhone: "+49 30 123456",
  orgWebAddress: "https://example.com",
  orgToC: "https://example.com/terms",

  // wallet solution details (for Wallet Provider TLs)
  walletSolutionName: "Example Wallet",
  walletSolutionRefId: "wallet-ref-001",
  walletSolutionUrl: "https://wallet.example.com",
};

const { data: tlr } = await tlClient.tlrCreate(tlId, payload, authHeader(token));

console.log("Created TLR:", tlr.id, tlr.did, tlr.status);

---

Onboarding via Verifiable Credential

The VC-based onboarding flow uses OID4VP. The operator initiates a session; the applicant scans a QR code and presents their Onboarding Credential. The operator polls for completion.

1. Initiate the onboarding session

import { DefaultApi, OnboardingPayload, OnboardingResponse } from "@idunion/tl-sdk";

const tlId = "my-trust-list-id";

const payload: OnboardingPayload = {
  verifierId: "verifier-xyz456",         // verifier configured on the TL
  holderEntityId: "did:key:z6Mk...",     // optional: pre-known did:key of the applicant
};

const { data: session } = await tlClient.onboardingInit(tlId, payload, authHeader(token));

// session.verifierState — opaque state token used to poll status
// session.verifierUrl  — OID4VP presentation request URL (encode as QR code for the applicant)
console.log("Onboarding session started:", session.verifierState);
console.log("QR code URL:", session.verifierUrl);

2. Poll for status

Poll onboardingStatus using the verifierState returned in step 1. The applicant scans the QR code and presents their credential in their wallet; the status transitions from in_progress to completed (or error).

import { OnboardingStatus, OnboardingStatusStatusEnum } from "@idunion/tl-sdk";

function pollOnboardingStatus(
  verifierState: string,
  intervalMs = 5000,
): Promise<OnboardingStatus> {
  return new Promise((resolve, reject) => {
    const timer = setInterval(async () => {
      const { data: status } = await tlClient.onboardingStatus(verifierState);

      switch (status.status) {
        case OnboardingStatusStatusEnum.Completed:
          clearInterval(timer);
          // status.did contains the newly registered DID
          resolve(status);
          break;

        case OnboardingStatusStatusEnum.Error:
          clearInterval(timer);
          reject(new Error(status.message ?? "Onboarding failed"));
          break;

        case OnboardingStatusStatusEnum.InProgress:
          // keep polling
          break;
      }
    }, intervalMs);
  });
}

const result = await pollOnboardingStatus(session.verifierState);
console.log("Onboarding complete. DID:", result.did);

---

Getting Trust List Records

All records for a Trust List

import { DefaultApi, TlrList, TlrStatusEnum } from "@idunion/tl-sdk";

const tlId = "my-trust-list-id";

const { data: tlrList } = await tlClient.tlrsGet(tlId, authHeader(token));

// tlrList.items — array of Tlr objects
for (const tlr of tlrList.items) {
  console.log(tlr.orgName, tlr.did, tlr.status);
}

// Filter by status
const trusted = tlrList.items.filter(
  (tlr) => tlr.status === TlrStatusEnum.Trusted,
);

TlrStatusEnum values:

Value	Meaning
TlrStatusEnum.Onboarded	Onboarded via a VC (issuer not verified by IDunion SCE)
TlrStatusEnum.Trusted	Onboarded via a VC whose issuer is verified by IDunion SCE
TlrStatusEnum.Revoked	Verification Method was revoked
TlrStatusEnum.Expired	Verification Method or Onboarding VC has expired

Single record

const tlrId = "some-tlr-id";

const { data: tlr } = await tlClient.tlrGet(tlId, tlrId, authHeader(token));

console.log(tlr.orgName, tlr.did, tlr.isRoot, tlr.status);

Search across all Trust Lists by organisation name

const { data: results } = await tlClient.tlrSearch("Example GmbH");

for (const tlr of results.items) {
  console.log(tlr.tlName, tlr.orgName, tlr.did);
}

---

Getting the Trust List in XML Format

The SDK exposes etsiTlGet which returns the ETSI TS 119 602 Trust List as a structured object. To download the raw XML file, construct the URL from the didBase field of the Trust List.

Via SDK method

const tlId = "my-trust-list-id";

const { data: etsiTl } = await tlClient.etsiTlGet(tlId);

// etsiTl is the ETSI Trust List as a parsed object
console.log(etsiTl);

Direct XML URL from didBase

The Tl object returned by tlCreate / tlGet includes a didBase field (a did:web DID). Convert it to an HTTPS base URL and append the ETSI path to get the XML download link.

import { DefaultApi, Tl } from "@idunion/tl-sdk";

function tlXmlUrl(tl: Tl): string {
  let host = tl.didBase
    .replace("did:web:", "")
    .replaceAll(":", "/");
  host = decodeURIComponent(host);
  const schema = host.startsWith("localhost") ? "http://" : "https://";
  return `${schema}${host}/etsi/119_602_tl.xml`;
}

const { data: tl } = await tlClient.tlGet(tlId, authHeader(token));

const xmlUrl = tlXmlUrl(tl);
console.log("XML download URL:", xmlUrl);
// e.g. https://tl.example.com/my-trust-list-id/etsi/119_602_tl.xml