admiral-sdk-ts

TypeScript client library for the Admiral API.

Built on ConnectRPC, and works in both browsers and Node.js.

Installation

npm install @admiral-io/sdk

You also need a Connect transport for your runtime:

# Browser
npm install @connectrpc/connect-web

# Node.js
npm install @connectrpc/connect-node

Quick Start

import { createClient } from "@admiral-io/sdk";

Browser

import { createConnectTransport } from "@connectrpc/connect-web";

const transport = createConnectTransport({
  baseUrl: "/api",
});

const client = createClient(transport);
// await client.agent.methodName({ ... });
// await client.job.methodName({ ... });
// await client.agentRuntime.methodName({ ... });
// await client.apiKey.methodName({ ... });
// await client.application.methodName({ ... });
// await client.changeSet.methodName({ ... });
// await client.credential.methodName({ ... });
// await client.environment.methodName({ ... });
// await client.healthcheck.methodName({ ... });
// await client.integration.methodName({ ... });
// await client.invitation.methodName({ ... });
// await client.registry.methodName({ ... });
// await client.run.methodName({ ... });
// await client.serviceAccount.methodName({ ... });
// await client.issuer.methodName({ ... });
// await client.source.methodName({ ... });
// await client.tenant.methodName({ ... });
// await client.user.methodName({ ... });

Node.js

import { createConnectTransport } from "@connectrpc/connect-node";

const transport = createConnectTransport({
  baseUrl: "https://api.admiral.io",
  httpVersion: "2",
});

const client = createClient(transport);

Available Services

Example

import { createConnectTransport } from "@connectrpc/connect-node";
import { createClient } from "@admiral-io/sdk";

async function main() {
  const transport = createConnectTransport({
    baseUrl: "https://api.admiral.io",
    httpVersion: "2",
  });

  const client = createClient(transport);

  try {
    const response = await client.agent.listMethod({});
    console.log(response);
  } catch (err) {
    console.error("Request failed:", err);
  }
}

main();

Interceptors

Auth, logging, timeouts, and other cross-cutting concerns are configured on the transport via Connect interceptors:

import type { Interceptor } from "@connectrpc/connect";
import { createConnectTransport } from "@connectrpc/connect-web";
import { createClient } from "@admiral-io/sdk";

const authInterceptor: Interceptor = (next) => async (req) => {
  req.header.set("Authorization", `Bearer ${getToken()}`);
  return next(req);
};

const transport = createConnectTransport({
  baseUrl: "/api",
  interceptors: [authInterceptor],
});

const client = createClient(transport);

Token Validation

Validate Admiral opaque token format (prefix, length, CRC32 checksum) without a network call:

import { validateAuthToken } from "@admiral-io/sdk";

const result = validateAuthToken(token);
if (!result.valid) {
  console.error(result.error);
}

A custom TokenValidator can be provided for alternative validation strategies:

import type { TokenValidator } from "@admiral-io/sdk";

const myValidator: TokenValidator = {
  validate(token: string) {
    // Custom validation logic
    return { valid: token.length > 0 };
  },
};

Requirements

• Node.js >= 22 (for Node.js usage)
• ESM only (no CommonJS support)

Admiral

Admiral is a control plane for coordinating infrastructure and application delivery across environments. This repository is one of its open-source tools.

• Documentation
• A bug in this repository: open an issue
• Anything else about Admiral, or not sure where it goes: admiral-community
• A security vulnerability: email [email protected], never a public issue

License

Apache-2.0 License - see LICENSE for details.