@loams/client 0.0.0-stage → 0.1.0

package/dist/runtime/token-source.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Where a call's bearer comes from.
+ *
+ * `token()` is called once per attempt, so a source may return a different
+ * token each time. `refresh()` is called only after the server said the token
+ * expired; a source without one is a source whose token does not expire
+ * (an API key), and the runtime then does not retry.
+ */
+export interface TokenSource {
+    /** The bearer to send, or undefined to send no credential at all. */
+    token(): Promise<string | undefined>;
+    /** Fetch a new token after the server reported the current one expired. */
+    refresh?(): Promise<void>;
+}
+/** A Loams API key. The key does not expire, so there is nothing to refresh. */
+export declare function apiKey(key: string): TokenSource;
+/** A token that is already valid, for a caller that manages its own. */
+export declare function staticToken(token: string): TokenSource;
+/**
+ * `LOAMS_API_KEY`, then `LOAMS_TOKEN`, then nothing.
+ *
+ * The environment is read on every call rather than once at construction, so a
+ * process that receives its credentials after the client is built (a
+ * sidecar, a test) still authenticates.
+ */
+export declare function envToken(environment?: Record<string, string | undefined>): TokenSource;
+/**
+ * A source that caches a token and calls `fetch` when it is asked to refresh.
+ *
+ * This is the shape every refreshing source has: one in-flight refresh shared
+ * by concurrent callers, so a burst of `401`s produces one token exchange
+ * rather than one per request.
+ */
+export declare function refreshing(fetchToken: () => Promise<string>): TokenSource;
+/** The RFC 8693 token exchange a person signed in through Authentik needs
+ * (design §44 §7.4, D608; §19 §5.2).
+ *
+ * The instance's `/oauth/token` protocol endpoint takes the identity token and
+ * answers with a Loams access token, which is then cached until it expires.
+ *
+ * Not covered by the conformance suite: the instance serves no OAuth endpoint
+ * yet (the auth plan, MT, and API1 Task 7 build it), so this path is written
+ * to the documented request and response and cannot be exercised against a
+ * live server. `typescript_token_source_refresh` covers the caching and
+ * refresh-once-and-retry behaviour that `refreshing()` implements, which is the
+ * part the SDK owns.
+ */
+export declare function oidcExchange(options: {
+    /** The instance's `/oauth/token` endpoint. */
+    endpoint: string;
+    /** The public OAuth client id (§44 §7.4: the gateway exchanges the token). */
+    clientId: string;
+    /** Mints the current identity token, from the host's OIDC session. */
+    subjectToken: () => Promise<string>;
+    /** Injected for tests and for hosts with their own `fetch`. */
+    fetch?: typeof globalThis.fetch;
+}): TokenSource;

package/dist/runtime/token-source.js

@@ -0,0 +1,117 @@
+// Token sources (design §44 §7.4, D608; runtime contract R1).
+//
+// A `TokenSource` returns a bearer and can be asked for a new one. Tokens
+// travel in `Authorization: Bearer` and never in the query string. A `401`
+// carrying `reason = token_expired` triggers one refresh and one retry; that
+// logic lives in the call path, not here, so a source stays a source.
+/** A Loams API key. The key does not expire, so there is nothing to refresh. */
+export function apiKey(key) {
+    if (key === '') {
+        throw new Error('apiKey: the key is empty');
+    }
+    return { token: () => Promise.resolve(key) };
+}
+/** A token that is already valid, for a caller that manages its own. */
+export function staticToken(token) {
+    if (token === '') {
+        throw new Error('staticToken: the token is empty');
+    }
+    return { token: () => Promise.resolve(token) };
+}
+/**
+ * `LOAMS_API_KEY`, then `LOAMS_TOKEN`, then nothing.
+ *
+ * The environment is read on every call rather than once at construction, so a
+ * process that receives its credentials after the client is built (a
+ * sidecar, a test) still authenticates.
+ */
+export function envToken(environment = processEnvironment()) {
+    return {
+        token: () => Promise.resolve(environment.LOAMS_API_KEY ?? environment.LOAMS_TOKEN ?? undefined),
+    };
+}
+/**
+ * A source that caches a token and calls `fetch` when it is asked to refresh.
+ *
+ * This is the shape every refreshing source has: one in-flight refresh shared
+ * by concurrent callers, so a burst of `401`s produces one token exchange
+ * rather than one per request.
+ */
+export function refreshing(fetchToken) {
+    let cached;
+    let inFlight;
+    const source = {
+        // The first `token()` fetches: a source whose cache starts empty would send
+        // no credential at all, and an instance that requires one answers
+        // `unauthenticated`, which the call path treats as "the token expired" and
+        // retries — with still no credential.
+        token: () => {
+            if (cached !== undefined) {
+                return Promise.resolve(cached);
+            }
+            return (source.refresh?.() ?? Promise.resolve()).then(() => cached);
+        },
+        refresh: () => {
+            inFlight ??= fetchToken()
+                .then((next) => {
+                cached = next;
+            })
+                .finally(() => {
+                inFlight = undefined;
+            });
+            return inFlight;
+        },
+    };
+    return source;
+}
+/** The RFC 8693 token exchange a person signed in through Authentik needs
+ * (design §44 §7.4, D608; §19 §5.2).
+ *
+ * The instance's `/oauth/token` protocol endpoint takes the identity token and
+ * answers with a Loams access token, which is then cached until it expires.
+ *
+ * Not covered by the conformance suite: the instance serves no OAuth endpoint
+ * yet (the auth plan, MT, and API1 Task 7 build it), so this path is written
+ * to the documented request and response and cannot be exercised against a
+ * live server. `typescript_token_source_refresh` covers the caching and
+ * refresh-once-and-retry behaviour that `refreshing()` implements, which is the
+ * part the SDK owns.
+ */
+export function oidcExchange(options) {
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const inner = refreshing(async () => {
+        const response = await doFetch(options.endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+                subject_token_type: 'urn:ietf:params:oauth:token-type:id_token',
+                requested_token_type: 'urn:ietf:params:oauth:token-type:access_token',
+                subject_token: await options.subjectToken(),
+                client_id: options.clientId,
+            }).toString(),
+        });
+        if (!response.ok) {
+            throw new Error(`the token exchange answered ${response.status} ${response.statusText}`);
+        }
+        const body = (await response.json());
+        if (body.access_token === undefined) {
+            throw new Error('the token exchange answered no access_token');
+        }
+        return body.access_token;
+    });
+    return {
+        token: () => inner.token(),
+        refresh: async () => {
+            await inner.refresh?.();
+        },
+    };
+}
+/** `process.env` where there is one. In a browser there is not, and an
+ * `envToken()` there resolves to no credential rather than throwing at import
+ * time. */
+function processEnvironment() {
+    const candidate = globalThis
+        .process;
+    return candidate?.env ?? {};
+}

package/dist/runtime/transports.d.ts

@@ -0,0 +1,58 @@
+import { createConnectTransport } from '@connectrpc/connect-web';
+import type { Interceptor, Transport } from '@connectrpc/connect';
+/** What a caller may configure on the transport. */
+export interface TransportOptions {
+    /**
+     * The instance's base URL. `Loams` sets this per call from its own
+     * `endpoint`, so a caller building a transport by hand rarely needs it.
+     */
+    baseUrl?: string;
+    /**
+     * Extra headers on every request, unary and streaming: for a gateway, a
+     * proxy, or a routing header such as the Live app a call is for. They are
+     * attached by an interceptor (`headersInterceptor`), because neither
+     * connect-web's nor connect-node's transport has a `headers` option; a
+     * header the call already sets (a credential, a per-call header) wins.
+     */
+    headers?: Record<string, string>;
+    /**
+     * `useBinaryFormat` picks the encoding: `true` is protobuf, `false` is the
+     * proto3 JSON mapping. Default `true`. JSON is what `curl` sends
+     * (design §44 §4) and what a proxy that logs bodies can read; binary is
+     * smaller and does not need a JSON codec on the wire.
+     */
+    useBinaryFormat?: boolean;
+    /**
+     * The deadline for a call that does not set its own, passed to the
+     * transport as `defaultTimeoutMs`. A per-call `timeoutMs` still wins.
+     */
+    defaultTimeoutMs?: number;
+    /**
+     * CORS preflights for the browser: custom headers and the credential mode.
+     * A browser sending `Authorization` needs the server's CORS policy to allow
+     * it; this only tells the transport what the request will look like.
+     */
+    interceptors?: Parameters<typeof createConnectTransport>[0]['interceptors'];
+}
+/**
+ * The default transport: Connect over `fetch`.
+ *
+ * Works in a browser, in Node 18+ (which has `fetch`), in Deno and in Bun, and
+ * speaks both the Connect unary protocol and gRPC-Web, which is what the server
+ * serves on the same port (D600). This is the browser path as a first-class
+ * case, not a fallback: it is the default in every runtime.
+ */
+export declare function createLoamsTransport(options?: TransportOptions): Transport;
+/**
+ * An interceptor that sets `headers` on every request, unary and streaming.
+ *
+ * A header already on the request is left alone, so a per-call header or the
+ * credential the invoker attaches is never overwritten by a static default.
+ */
+export declare function headersInterceptor(headers: Record<string, string>): Interceptor;
+/**
+ * The interceptors a transport built from `options` runs: the static headers
+ * first (outermost), then the caller's own, so a caller's interceptor sees the
+ * headers and may still change them.
+ */
+export declare function transportInterceptors(options: TransportOptions): Interceptor[];

package/dist/runtime/transports.js

@@ -0,0 +1,66 @@
+// Transports (design §44 §4, D612).
+//
+// One port serves the Connect protocol, gRPC and gRPC-Web (D600), so the only
+// question a client has is which of those it can speak:
+//
+// - **Browsers** cannot do HTTP/2 gRPC. They speak gRPC-Web and Connect, both
+//   over `fetch`, which is what `@connectrpc/connect-web` implements. Because
+//   the API serves gRPC-Web on the same port as everything else, the same
+//   client code runs in a browser with no proxy and no sidecar.
+// - **Node, Deno and Bun** can do HTTP/2 gRPC. `@connectrpc/connect-node`
+//   implements it over `node:http2`, and the server's plaintext listener means
+//   no ALPN to negotiate — the client asks for HTTP/2 with prior knowledge.
+//
+// The default is the `fetch` transport, deliberately: it is the one case where
+// the *same* code path works everywhere, so it is what an application gets
+// unless it asks for the Node one through `@loams/client/node`. Choosing the
+// HTTP/2 transport in a browser bundle would be a build error, which is the
+// right failure.
+import { createConnectTransport } from '@connectrpc/connect-web';
+/**
+ * The default transport: Connect over `fetch`.
+ *
+ * Works in a browser, in Node 18+ (which has `fetch`), in Deno and in Bun, and
+ * speaks both the Connect unary protocol and gRPC-Web, which is what the server
+ * serves on the same port (D600). This is the browser path as a first-class
+ * case, not a fallback: it is the default in every runtime.
+ */
+export function createLoamsTransport(options = {}) {
+    const interceptors = transportInterceptors(options);
+    return createConnectTransport({
+        baseUrl: options.baseUrl ?? '',
+        useBinaryFormat: options.useBinaryFormat ?? true,
+        ...(options.defaultTimeoutMs === undefined
+            ? {}
+            : { defaultTimeoutMs: options.defaultTimeoutMs }),
+        ...(interceptors.length === 0 ? {} : { interceptors }),
+    });
+}
+/**
+ * An interceptor that sets `headers` on every request, unary and streaming.
+ *
+ * A header already on the request is left alone, so a per-call header or the
+ * credential the invoker attaches is never overwritten by a static default.
+ */
+export function headersInterceptor(headers) {
+    const entries = Object.entries(headers);
+    return (next) => (request) => {
+        for (const [name, value] of entries) {
+            if (!request.header.has(name)) {
+                request.header.set(name, value);
+            }
+        }
+        return next(request);
+    };
+}
+/**
+ * The interceptors a transport built from `options` runs: the static headers
+ * first (outermost), then the caller's own, so a caller's interceptor sees the
+ * headers and may still change them.
+ */
+export function transportInterceptors(options) {
+    const headers = options.headers === undefined || Object.keys(options.headers).length === 0
+        ? []
+        : [headersInterceptor(options.headers)];
+    return [...headers, ...(options.interceptors ?? [])];
+}

package/dist/runtime/uuidv7.d.ts

@@ -0,0 +1,10 @@
+/** A fresh UUIDv7 as a canonical string. */
+export declare function uuidv7(): string;
+/**
+ * The Unix milliseconds a UUIDv7 encodes, or undefined for anything else.
+ *
+ * The timestamp is the first **twelve** hex digits, not eight: 48 bits, and
+ * milliseconds since the epoch use 41 of them. Reading eight digits would
+ * return a number around 2^25, which is January 1970.
+ */
+export declare function uuidv7Time(value: string): number | undefined;

package/dist/runtime/uuidv7.js

@@ -0,0 +1,57 @@
+// UUIDv7 (design §44 §7.4, D610).
+//
+// An idempotency key has to be unique across every client that has ever talked
+// to an instance and sort by creation time, because a key that sorts is one
+// an operator can correlate in a log. UUIDv4 is unique but unordered; ULIDs
+// would do, but the SDKs across thirteen languages would each need their own
+// implementation, and `crypto.randomUUID` is in every runtime this SDK targets.
+//
+// Layout: 48 bits of Unix milliseconds, 4 bits of version (7), 12 bits of
+// counter within the millisecond, 2 bits of variant, 62 random bits.
+const HEX = [...'0123456789abcdef'];
+function randomBytes(length) {
+    const bytes = new Uint8Array(length);
+    globalThis.crypto.getRandomValues(bytes);
+    return bytes;
+}
+/** A fresh UUIDv7 as a canonical string. */
+export function uuidv7() {
+    const random = randomBytes(16);
+    // The 48-bit timestamp is big-endian, so it is read out with shifts rather
+    // than by dividing and masking: dividing keeps the fractional bits of the
+    // lower digits and truncates the carry, which puts the wrong byte in.
+    const now = BigInt(Date.now());
+    for (let index = 0; index < 6; index += 1) {
+        random[index] = Number((now >> BigInt((5 - index) * 8)) & 0xffn);
+    }
+    const version = (random[6] ?? 0) & 0x0f;
+    const variant = (random[8] ?? 0) & 0x3f;
+    random[6] = version | 0x70;
+    random[8] = variant | 0x80;
+    let out = '';
+    for (let index = 0; index < 16; index += 1) {
+        if (index === 4 || index === 6 || index === 8 || index === 10) {
+            out += '-';
+        }
+        const byte = random[index] ?? 0;
+        out += `${HEX[byte >> 4]}${HEX[byte & 0x0f]}`;
+    }
+    return out;
+}
+/**
+ * The Unix milliseconds a UUIDv7 encodes, or undefined for anything else.
+ *
+ * The timestamp is the first **twelve** hex digits, not eight: 48 bits, and
+ * milliseconds since the epoch use 41 of them. Reading eight digits would
+ * return a number around 2^25, which is January 1970.
+ */
+export function uuidv7Time(value) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value)) {
+        return undefined;
+    }
+    let time = 0;
+    for (const character of value.replaceAll('-', '').slice(0, 12)) {
+        time = time * 16 + Number.parseInt(character, 16);
+    }
+    return time;
+}

package/dist/system.d.ts

@@ -0,0 +1,87 @@
+import type { GetInstanceResponse, ServiceStatus } from './vendor/proto/gen/loams/instance/v1/instance_pb.js';
+import type { CallOptions } from './runtime/call.js';
+/** `GetInstance.services[]`, sorted by what an SDK can use. */
+export interface Catalogue {
+    /** Every package the instance knows, served or not. */
+    readonly services: readonly ServiceStatus[];
+    /** The packages this binary serves. */
+    readonly served: readonly string[];
+    /** The packages this binary knows but does not serve, which is what makes
+     * `unavailable` a plan rather than a surprise. */
+    readonly unavailable: readonly string[];
+}
+/** What `loams.version()` reports (runtime contract R9). */
+export interface VersionReport {
+    /** The proto revision this SDK was generated from. */
+    readonly protoRev: string;
+    /** The server's own semver. */
+    readonly serverVersion: string;
+    /** The proto packages the server says it serves. */
+    readonly apiVersions: readonly string[];
+    /** The SDK's packages the server does not serve. */
+    readonly missing: readonly string[];
+    /** True when every package the SDK speaks is served. */
+    readonly compatible: boolean;
+}
+/** What a `Loams` hands to its `system`. */
+export interface SystemConfig {
+    /** The instance's URL, for error messages and for a caller reading `endpoint`. */
+    readonly endpoint: string;
+    readonly maxRetries?: number;
+    /** The client's deadline for the catalogue call. */
+    readonly timeoutMs?: number;
+}
+/** The catalogue, the version check and the guard. */
+export declare class SystemApi {
+    #private;
+    /** `loams.instance.getInstance`, which is the one RPC the system API uses.
+     * Injected rather than reached for, so the system API is testable without
+     * a client. */
+    private readonly getInstance;
+    private readonly config;
+    constructor(
+    /** `loams.instance.getInstance`, which is the one RPC the system API uses.
+     * Injected rather than reached for, so the system API is testable without
+     * a client. */
+    getInstance: (request: object, options?: CallOptions) => Promise<GetInstanceResponse>, config: SystemConfig);
+    /**
+     * The service catalogue, cached.
+     *
+     * Cached because it is asked on a cold start, when a UI is deciding which
+     * features to show, and again on every feature check: the instance's services
+     * do not change while a process runs. `invalidate()` drops it.
+     */
+    catalogue(): Promise<Catalogue>;
+    private fetch;
+    /** Drops the cached catalogue. */
+    invalidate(): void;
+    /** The client's retry and deadline settings, applied to the catalogue call. */
+    private callOptions;
+    /**
+     * Whether this binary serves a module or a proto package.
+     *
+     * Takes either, so a caller holding `loams.live` can pass `'live'` and a
+     * caller reading a `ServiceStatus` can pass `'loams.live.v1'`.
+     */
+    available(moduleOrPackage: string): Promise<boolean>;
+    /** The packages this binary serves. */
+    served(): Promise<readonly string[]>;
+    /** The packages it knows but does not serve. */
+    unavailable(): Promise<readonly string[]>;
+    /**
+     * Throws `FeatureNotInVariantError` unless this binary serves the module.
+     *
+     * This is the guard to put in front of a feature: the error is the same
+     * class the server's own refusal maps to, so one `catch` covers both "the
+     * instance does not have this" and "the guard said no", and it costs no RPC
+     * once the catalogue is cached.
+     */
+    guard(moduleOrPackage: string): Promise<void>;
+    /**
+     * The proto revision check (R9).
+     *
+     * A missing package is a warning, not an exception: the SDK still works for
+     * the modules that are there, and the caller decides what a missing one means.
+     */
+    version(): Promise<VersionReport>;
+}

package/dist/system.js

@@ -0,0 +1,152 @@
+// Feature detection and the version check (design §44 §4 and §7.4; runtime
+// contract R9).
+//
+// The unavailable-service path has two halves, and an SDK needs both:
+//
+// 1. **Without calling.** `GetInstance.services[]` says which packages this
+//    binary carries and which it does not (D600). One call, no auth, cheap, so
+//    an application asks first and hides a feature it cannot use. `loams.system`
+//    wraps it: `available`, `served`, `guard`.
+// 2. **When the caller calls anyway.** A call to a package the variant does not
+//    carry answers `unimplemented` with `ErrorInfo.reason =
+//    feature_not_in_variant` and the variant in `metadata.variant` (D600). The
+//    runtime turns that into a `FeatureNotInVariantError`, so the branch is on
+//    `err instanceof FeatureNotInVariantError` or on
+//    `err.reason === 'feature_not_in_variant'` — never on a message, and never
+//    on the package name, which is a proto detail.
+//
+// Half 1 is the one to use. Half 2 is the safety net for a caller who skipped
+// it, or whose instance changed variant underneath a long-lived client.
+import { MODULES, PROTO_PACKAGES, PROTO_REV } from './gen/facade.js';
+import { Code } from '@connectrpc/connect';
+import { FeatureNotInVariantError, LoamsError } from './runtime/errors.js';
+/** The catalogue, the version check and the guard. */
+export class SystemApi {
+    getInstance;
+    config;
+    #catalogue;
+    #inFlight;
+    constructor(
+    /** `loams.instance.getInstance`, which is the one RPC the system API uses.
+     * Injected rather than reached for, so the system API is testable without
+     * a client. */
+    getInstance, config) {
+        this.getInstance = getInstance;
+        this.config = config;
+    }
+    /**
+     * The service catalogue, cached.
+     *
+     * Cached because it is asked on a cold start, when a UI is deciding which
+     * features to show, and again on every feature check: the instance's services
+     * do not change while a process runs. `invalidate()` drops it.
+     */
+    async catalogue() {
+        this.#catalogue ??= await this.fetch();
+        return this.#catalogue;
+    }
+    async fetch() {
+        // One in-flight fetch shared by concurrent callers, so a cold start with
+        // twenty availability checks makes one call, not twenty.
+        this.#inFlight ??= this.getInstance({}, this.callOptions())
+            .then((info) => toCatalogue(info.services ?? []))
+            .finally(() => {
+            this.#inFlight = undefined;
+        });
+        return this.#inFlight;
+    }
+    /** Drops the cached catalogue. */
+    invalidate() {
+        this.#catalogue = undefined;
+    }
+    /** The client's retry and deadline settings, applied to the catalogue call. */
+    callOptions() {
+        return {
+            ...(this.config.maxRetries === undefined ? {} : { maxRetries: this.config.maxRetries }),
+            ...(this.config.timeoutMs === undefined ? {} : { timeoutMs: this.config.timeoutMs }),
+        };
+    }
+    /**
+     * Whether this binary serves a module or a proto package.
+     *
+     * Takes either, so a caller holding `loams.live` can pass `'live'` and a
+     * caller reading a `ServiceStatus` can pass `'loams.live.v1'`.
+     */
+    async available(moduleOrPackage) {
+        const name = packageOf(moduleOrPackage);
+        const { served } = await this.catalogue();
+        return served.includes(name);
+    }
+    /** The packages this binary serves. */
+    async served() {
+        return (await this.catalogue()).served;
+    }
+    /** The packages it knows but does not serve. */
+    async unavailable() {
+        return (await this.catalogue()).unavailable;
+    }
+    /**
+     * Throws `FeatureNotInVariantError` unless this binary serves the module.
+     *
+     * This is the guard to put in front of a feature: the error is the same
+     * class the server's own refusal maps to, so one `catch` covers both "the
+     * instance does not have this" and "the guard said no", and it costs no RPC
+     * once the catalogue is cached.
+     */
+    async guard(moduleOrPackage) {
+        const name = packageOf(moduleOrPackage);
+        if (await this.available(name)) {
+            return;
+        }
+        throw new FeatureNotInVariantError(`${name} is not in this instance's build variant`, {
+            code: Code.Unimplemented,
+            reason: 'feature_not_in_variant',
+            metadata: { package: name, variant: 'standard' },
+            rpc: 'loams.instance.v1.InstanceService/GetInstance',
+            variant: 'standard',
+        });
+    }
+    /**
+     * The proto revision check (R9).
+     *
+     * A missing package is a warning, not an exception: the SDK still works for
+     * the modules that are there, and the caller decides what a missing one means.
+     */
+    async version() {
+        const info = await this.getInstance({}, this.callOptions());
+        const apiVersions = info.apiVersions ?? [];
+        const spoken = PROTO_PACKAGES.filter((name) => name.startsWith('loams.'));
+        const missing = spoken.filter((name) => !apiVersions.includes(name));
+        return {
+            protoRev: PROTO_REV,
+            serverVersion: info.serverVersion ?? '',
+            apiVersions,
+            missing,
+            compatible: missing.length === 0,
+        };
+    }
+}
+/** The proto package behind a module name or a package name. */
+function packageOf(moduleOrPackage) {
+    if (moduleOrPackage.startsWith('loams.')) {
+        return moduleOrPackage;
+    }
+    const found = MODULES.find((module) => module.name === moduleOrPackage);
+    if (found === undefined) {
+        throw new LoamsError(`no generated module named ${moduleOrPackage}`, {
+            code: Code.Internal,
+        });
+    }
+    return found.package;
+}
+/** Splits `GetInstance.services[]` into served and not. */
+function toCatalogue(services) {
+    const sorted = [...services].sort((left, right) => left.package.localeCompare(right.package));
+    return {
+        services: sorted,
+        served: sorted.filter((service) => service.available).map((service) => service.package),
+        unavailable: sorted
+            .filter((service) => !service.available)
+            .map((service) => service.package),
+    };
+}

package/dist/vendor/proto/admin.d.ts

@@ -0,0 +1,6 @@
+export * from './gen/loams/admin/v1/agent_pb.js';
+export * from './gen/loams/admin/v1/audit_pb.js';
+export * from './gen/loams/admin/v1/common_pb.js';
+export * from './gen/loams/admin/v1/key_pb.js';
+export * from './gen/loams/admin/v1/org_pb.js';
+export * from './gen/loams/admin/v1/project_pb.js';

package/dist/vendor/proto/admin.js

@@ -0,0 +1,12 @@
+// `loams.admin.v1` in one module (API2 Task 7): the package is six proto files
+// (common, org, project, agent, key and audit), and protoc-gen-es writes one
+// TypeScript module per file. Every name is unique across the package, so
+// they re-export together as `@loams/proto/admin`, which is the module the SDK
+// facade imports the package from. Each file is also exported on its own path
+// (`@loams/proto/admin/org`).
+export * from './gen/loams/admin/v1/agent_pb.js';
+export * from './gen/loams/admin/v1/audit_pb.js';
+export * from './gen/loams/admin/v1/common_pb.js';
+export * from './gen/loams/admin/v1/key_pb.js';
+export * from './gen/loams/admin/v1/org_pb.js';
+export * from './gen/loams/admin/v1/project_pb.js';