One port, three protocols, one client object

import { Loams, apiKey, FeatureNotInVariantError } from '@loams/client';

const loams = new Loams({
  endpoint: 'http://127.0.0.1:8080',
  auth: apiKey(process.env.LOAMS_API_KEY!),   // or envToken(), oidcExchange({…})
});

const info = await loams.instance.getInstance({});   // no auth needed
await loams.system.guard('live');                    // costs no RPC once cached

try {
  await loams.tables.mutate(request);
} catch (error) {
  if (error instanceof FeatureNotInVariantError) {
    // This build variant does not carry loams.live.v1.
    console.warn(error.variant);                    // 'standard'
  }
}

const { served, unavailable } = await loams.system.catalogue();

if (await loams.system.available('live')) {
  // loams.live.v1 is in this build.
}

// Guarded, the same check that throws FeatureNotInVariantError the server's
// own refusal maps to, so one catch covers both paths:
try {
  await loams.system.guard('live');
} catch (error) {
  if (error instanceof FeatureNotInVariantError) {
    console.warn(`${error.reason}: ${error.variant}`);
  }
}

// The SDK's packages against the server's, as a compatibility report:
const report = await loams.system.version();
console.log(report.protoRev, report.serverVersion, report.missing);

import {
  LoamsError,
  FeatureNotInVariantError,
  TokenExpiredError,
  isLoamsError,
} from '@loams/client';

try {
  await loams.instance.getInstance({});
} catch (error) {
  if (error instanceof FeatureNotInVariantError) {
    // reason: 'feature_not_in_variant', metadata.variant: 'standard'
  } else if (error instanceof TokenExpiredError) {
    // The SDK has already refreshed once and retried; this is the second failure.
  } else if (isLoamsError(error)) {
    const { code, reason, metadata, hint } = error as LoamsError;
    // A reason this SDK version does not know is still a reason: the registry
    // only grows, so fall through to the code.
  }
}

// Node, Deno, Bun and browsers: Connect over fetch (the default).
const loams = new Loams({ endpoint });

// Node only: HTTP/2 gRPC, from the /node subpath so a bundler never follows
// the Node transport into a browser build it cannot satisfy.
import { createNodeTransport } from '@loams/client/node';
const overHttp2 = new Loams({ endpoint, transport: createNodeTransport() });

// Browsers: gRPC-Web. Same client code, same typed answers.
import { createGrpcWebTransport } from '@connectrpc/connect-web';
const inBrowser = new Loams({
  endpoint,
  transport: createGrpcWebTransport({ baseUrl: endpoint }),
});

const loams = new Loams({ endpoint, auth: apiKey(key), sessionConsistency: true });

await loams.tables.mutate(request);   // its ConsistencyToken is recorded
const rows = await loams.tables.query(request);   // carries the merged token

// Or per call, without the session:
await loams.tables.query(request, { consistency: 'EVENTUAL' });

curl -s http://127.0.0.1:8080/loams.collection.v1.QueryService/Search \
  -H 'content-type: application/json' \
  -d '{
    "namespace": "demo",
    "collection": "kb",
    "retrievers": [
      {"vector": {"field": "embedding", "query": [1, 0, 0], "k": 10}},
      {"text": {"query": {"match": {"field": "body", "text": "refund"}}, "k": 10}}
    ],
    "fusion": {"rrf": {"k": 60}},
    "limit": 3
  }'

curl -s http://127.0.0.1:8080/loams.instance.v1.InstanceService/GetInstance \
  -H 'content-type: application/json' \
  -d '{}'

# The same call as a GET, which a cache may store:
curl -s -G http://127.0.0.1:8080/loams.instance.v1.InstanceService/GetInstance \
  --data-urlencode 'encoding=json' --data-urlencode 'message={}'

curl -s http://127.0.0.1:8080/loams.instance.v1.InstanceService/WhoAmI \
  -H 'content-type: application/json' \
  -d '{}'

# With authentication off:
# { "principal": { "id": "dev-loopback", "displayName": "Local developer" } }

# With LOAMS_AUTH_MODE=apikey, the key is read from the environment:
curl -s http://127.0.0.1:8080/loams.instance.v1.InstanceService/WhoAmI \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $LOAMS_API_KEY" \
  -d '{}'

curl -s http://127.0.0.1:8080/loams.live.v1.LiveService/Query \
  -H 'content-type: application/json' \
  -d '{}'

# 501, and the ErrorInfo decodes to:
#   reason: "feature_not_in_variant"
#   metadata: { "variant": "standard" }

# Health, over the Connect JSON mapping:
curl -s http://127.0.0.1:8080/grpc.health.v1.Health/Check \
  -H 'content-type: application/json' \
  -d '{"service":"loams.instance.v1.InstanceService"}'
# { "status": "SERVING" }

# Reflection, over real gRPC. Mounted in `loams dev`, off elsewhere:
grpcurl -plaintext 127.0.0.1:8080 list
grpcurl -plaintext 127.0.0.1:8080 describe loams.instance.v1.InstanceService