@registrystack/client 0.0.0 → 0.26.1

package/relay/client.d.ts

@@ -0,0 +1,408 @@
+export type JsonScalar = string | number | boolean | null
+export type JsonValue = JsonScalar | ReadonlyArray<JsonValue> | { readonly [key: string]: JsonValue }
+/** An integer that satisfies `Number.isSafeInteger` and the option's documented bounds. */
+export type SafeInteger = number
+
+export interface PrivateJwk {
+  readonly kty: string
+  readonly kid: string
+  readonly alg: string
+  readonly [member: string]: JsonValue
+}
+
+export interface PrivateKeyJwtConfig {
+  tokenEndpoint: string
+  clientId: string
+  clientKey: PrivateJwk
+  audience?: string | null
+  assertionLifetimeSeconds?: SafeInteger | null
+  refreshMarginSeconds?: SafeInteger | null
+  requestTimeoutMilliseconds?: SafeInteger | null
+  connectTimeoutMilliseconds?: SafeInteger | null
+  userAgent?: string | null
+  trustedRootCertificates?: string | null
+}
+
+export type RelayAuthorization =
+  | { static: string }
+  | { privateKeyJwt: PrivateKeyJwtConfig }
+
+export interface RelayClientConfig {
+  baseUrl: string
+  authorization?: RelayAuthorization | null
+  requestTimeoutMilliseconds?: SafeInteger | null
+  connectTimeoutMilliseconds?: SafeInteger | null
+  userAgent?: string | null
+  maxResponseBytes?: SafeInteger | null
+  trustedRootCertificates?: string | null
+}
+
+export type RecordFormat = 'json' | 'json-ld' | 'geojson' | 'json-fg'
+
+export interface ResourceListOptions {
+  pageSize?: SafeInteger | null
+}
+
+export interface ResourceContinuation {
+  cursor: string
+}
+
+export interface RecordOptions {
+  fields?: ReadonlyArray<string> | null
+  accessProfile?: string | null
+  format?: RecordFormat | null
+}
+
+export interface ListOptions extends RecordOptions {
+  pageSize?: SafeInteger | null
+  filters?: Readonly<Record<string, string>> | null
+}
+
+export interface SearchOptions extends RecordOptions {
+  pageSize?: SafeInteger | null
+  /** `[west, south, east, north]` in WGS84 longitude/latitude degrees. */
+  bbox: readonly [number, number, number, number]
+}
+
+export type LookupSelector = string | SafeInteger | boolean
+export type LookupSelectors = Readonly<Record<string, LookupSelector>>
+
+export interface RecordsRoute {
+  kind: 'records'
+  resource: string
+}
+
+export interface SearchRoute {
+  kind: 'search'
+  resource: string
+  search: string
+}
+
+export interface CollectionContinuation<Route extends RecordsRoute | SearchRoute = RecordsRoute | SearchRoute> {
+  route: Route
+  cursor: string
+  format: 'json' | 'json-ld' | 'geojson-rfc7946' | 'json-fg'
+  accessProfile?: string
+}
+
+export interface SdmxDataRequest {
+  agency: string
+  resource: string
+  /** A three-part `x.y.z` SDMX version. */
+  version: string
+  key?: string | null
+  constraints?: Readonly<Record<string, string>> | null
+  offset?: SafeInteger | null
+  limit?: SafeInteger | null
+  dimensionAtObservation?: string | null
+  format?: 'json' | 'csv' | null
+}
+
+export interface SdmxStructureRequest {
+  kind: 'dataflow' | 'datastructure'
+  agency: string
+  resource: string
+  /** A three-part `x.y.z` SDMX version. */
+  version: string
+}
+
+export interface ProbeStatus {
+  status: string
+}
+
+export interface Institution {
+  identifier: string
+  name: string
+}
+
+export interface Product {
+  name: string
+  version: string
+}
+
+export interface ApiBinding {
+  name: string
+  version: string
+}
+
+export interface AlignmentTarget {
+  name: string
+  version: string
+  status: string
+  cfrTarget?: string
+}
+
+export interface FormatProfileCapability {
+  id: string
+  uri: string
+  crs: string
+  conformsTo: ReadonlyArray<string>
+}
+
+export interface WireFormatCapability {
+  id: string
+  mediaType: string
+  formatProfiles: ReadonlyArray<FormatProfileCapability>
+}
+
+export interface BboxCapability {
+  crs: string
+  predicate: string
+  maximumLongitudeSpanDegrees: number
+  maximumLatitudeSpanDegrees: number
+}
+
+export interface SpatialQueryCapability {
+  bbox: BboxCapability
+}
+
+export interface ConsultationCapability {
+  family: 'consultation'
+  pattern: string
+  resourceIdentifier: string
+  operationIdentifier: string
+  accessProfileIdentifier: string
+  isDefault: boolean
+  disclosureProfile: string
+  schemaReference: string
+  semanticModelReference: string
+  contextReference: string
+  href: string
+  wireFormats: ReadonlyArray<WireFormatCapability>
+  spatialQuery?: SpatialQueryCapability
+  classificationReference?: string
+  processingReference?: string
+}
+
+export interface SdmxProfile {
+  sdmxRestVersion: string
+  sdmxDataJsonVersion: string
+  sdmxDataCsvVersion: string
+  sdmxStructureJsonVersion: string
+}
+
+export interface SdmxWireFormat {
+  id: string
+  mediaType: string
+}
+
+export interface SdmxStructureLinks {
+  dataflow: string
+  datastructure: string
+}
+
+export interface AggregateDataCapability {
+  family: 'aggregate-data'
+  pattern: string
+  statisticalDatasetIdentifier: string
+  operationIdentifier: string
+  profile: SdmxProfile
+  wireFormats: ReadonlyArray<SdmxWireFormat>
+  href: string
+  structureLinks: SdmxStructureLinks
+}
+
+export type Capability = ConsultationCapability | AggregateDataCapability
+
+export interface ServiceMetadata {
+  registryIdentifier: string
+  name: string
+  authority: Institution
+  operator: Institution | null
+  authoritativeScope: string
+  product: Product
+  apiBinding: ApiBinding
+  alignmentTargets: ReadonlyArray<AlignmentTarget>
+  capabilities: ReadonlyArray<Capability>
+  links: { self: string; resources: string; openapi: string }
+}
+
+export interface ResourceDocument {
+  resourceIdentifier: string
+  title: string
+  description: string
+  semanticClass: string
+  enumerationPosture: string
+  capabilities: ReadonlyArray<Capability>
+  links: { self: string }
+}
+
+export interface CursorPageInfo {
+  nextCursor: string | null
+}
+
+export interface RegistryMetadata {
+  registryIdentifier: string
+}
+
+export interface ResourceCollection {
+  items: ReadonlyArray<ResourceDocument>
+  pageInfo: CursorPageInfo
+  meta: RegistryMetadata
+}
+
+export interface ResourceEnvelope {
+  data: ResourceDocument
+  meta: RegistryMetadata
+}
+
+export interface RegistryRecord {
+  registryIdentifier: string
+  recordIdentifier: string
+  revisionIdentifier: string
+  lifecycleState: string
+  schemaReference: string
+  semanticModelReference: string
+  authorityIdentifier: string
+  recordedAt: string
+  domainData: Readonly<Record<string, JsonValue>>
+  '@id'?: string
+  '@type'?: string
+}
+
+export interface SourceRevision {
+  profile: string
+  status: string
+  value: string | null
+}
+
+export interface RecordLinks {
+  self: string
+  context: string
+  schema: string
+  semanticModel: string
+}
+
+export interface RecordMetadata {
+  operationIdentifier: string
+  accessProfile: string
+  family: string
+  pattern: string
+  disclosureProfile: string
+  contractRevision: string
+  sourceRevision: SourceRevision
+  selectedFields: ReadonlyArray<string>
+  links: RecordLinks
+}
+
+export interface RecordEnvelope {
+  data: RegistryRecord
+  meta: RecordMetadata
+  '@context'?: string
+}
+
+export interface RecordCollection {
+  items: ReadonlyArray<RegistryRecord>
+  pageInfo: CursorPageInfo
+  meta: RecordMetadata
+  '@context'?: string
+}
+
+export interface GeoJsonFeature {
+  type: string
+  id: string
+  geometry: JsonValue
+  properties: RegistryRecord
+  meta?: RecordMetadata
+  conformsTo?: ReadonlyArray<string>
+  featureType?: string
+  coordRefSys?: string
+}
+
+export interface GeoJsonFeatureCollection {
+  type: string
+  features: ReadonlyArray<GeoJsonFeature>
+  pageInfo: CursorPageInfo
+  meta: RecordMetadata
+  conformsTo?: ReadonlyArray<string>
+  featureType?: string
+  coordRefSys?: string
+}
+
+export type RecordResponse = RecordEnvelope | GeoJsonFeature
+export type RecordCollectionResponse = RecordCollection | GeoJsonFeatureCollection
+
+export interface CompleteOutcome<T> {
+  kind: 'complete'
+  value: T
+  traceId: string
+  etag?: string
+}
+
+export interface NotModifiedOutcome {
+  kind: 'notModified'
+  etag: string
+  traceId: string
+}
+
+export type Outcome<T> = CompleteOutcome<T> | NotModifiedOutcome
+
+export interface ResourcePageCompleteOutcome {
+  kind: 'complete'
+  value: ResourceCollection
+  continuation?: ResourceContinuation
+  traceId: string
+  etag?: string
+}
+
+export type ResourcePageOutcome = ResourcePageCompleteOutcome | NotModifiedOutcome
+
+export interface CollectionPageCompleteOutcome {
+  kind: 'complete'
+  value: RecordCollectionResponse
+  continuation?: CollectionContinuation
+  traceId: string
+  etag?: string
+}
+
+export type CollectionPageOutcome = CollectionPageCompleteOutcome | NotModifiedOutcome
+
+export interface RawCompleteOutcome {
+  kind: 'complete'
+  body: Buffer
+  mediaType: string
+  traceId: string
+  etag?: string
+}
+
+export type RawOutcome = RawCompleteOutcome | NotModifiedOutcome
+
+export interface RelayClientFailure extends Error {
+  readonly kind: string
+  readonly code?: string
+  readonly status?: number
+  readonly traceId?: string
+  readonly retryAfterSeconds?: number
+  readonly transportKind?: string
+  readonly tokenKind?: string
+}
+
+export declare class RelayClientError extends Error implements RelayClientFailure {
+  readonly kind: string
+  readonly code?: string
+  readonly status?: number
+  readonly traceId?: string
+  readonly retryAfterSeconds?: number
+  readonly transportKind?: string
+  readonly tokenKind?: string
+}
+
+export declare class RelayClient {
+  constructor(config: RelayClientConfig)
+  health(): Promise<CompleteOutcome<ProbeStatus>>
+  ready(): Promise<CompleteOutcome<ProbeStatus>>
+  openapi(etag?: string | null): Promise<RawOutcome>
+  serviceMetadata(etag?: string | null): Promise<Outcome<ServiceMetadata>>
+  resources(options?: ResourceListOptions | null, etag?: string | null): Promise<ResourcePageOutcome>
+  continueResources(continuation: ResourceContinuation, etag?: string | null): Promise<ResourcePageOutcome>
+  resource(resource: string, etag?: string | null): Promise<Outcome<ResourceEnvelope>>
+  listRecords(resource: string, options?: ListOptions | null, etag?: string | null): Promise<CollectionPageOutcome>
+  continueListRecords(continuation: CollectionContinuation<RecordsRoute>, etag?: string | null): Promise<CollectionPageOutcome>
+  readRecord(resource: string, recordIdentifier: string, options?: RecordOptions | null, etag?: string | null): Promise<Outcome<RecordResponse>>
+  lookup(resource: string, lookup: string, selectors: LookupSelectors, options?: RecordOptions | null, etag?: string | null): Promise<Outcome<RecordResponse>>
+  search(resource: string, search: string, options: SearchOptions, etag?: string | null): Promise<CollectionPageOutcome>
+  continueSearch(continuation: CollectionContinuation<SearchRoute>, etag?: string | null): Promise<CollectionPageOutcome>
+  artifact(artifactIdentifier: string, etag?: string | null): Promise<RawOutcome>
+  sdmxData(request: SdmxDataRequest, etag?: string | null): Promise<RawOutcome>
+  sdmxStructure(request: SdmxStructureRequest, etag?: string | null): Promise<RawOutcome>
+}

package/relay/client.js

@@ -0,0 +1,172 @@
+'use strict';
+
+const { types: { isProxy } } = require('node:util');
+const native = require('./index');
+
+const MAX_JSON_DEPTH = 128;
+const MAX_JSON_NODES = 100_000;
+const MAX_JSON_STRING_BYTES = 4 * 1024 * 1024;
+
+class RelayClientError extends Error {
+  constructor(envelope) {
+    super(envelope.message);
+    this.name = 'RelayClientError';
+    this.kind = envelope.kind;
+    for (const field of ['code', 'status', 'traceId', 'retryAfterSeconds', 'transportKind', 'tokenKind']) {
+      if (envelope[field] !== undefined && envelope[field] !== null) this[field] = envelope[field];
+    }
+  }
+}
+
+function normalize(error, fallbackKind) {
+  if (error instanceof RelayClientError) return error;
+  if (error instanceof Error && typeof error.message === 'string') {
+    try {
+      const envelope = JSON.parse(error.message);
+      if (envelope && typeof envelope === 'object' && typeof envelope.kind === 'string') {
+        return new RelayClientError(envelope);
+      }
+    } catch {
+      // napi argument conversion errors are not mapped Rust error envelopes.
+    }
+  }
+  if (fallbackKind) {
+    return new RelayClientError({
+      kind: fallbackKind,
+      message: fallbackKind === 'configuration'
+        ? 'Relay client configuration is invalid'
+        : 'Relay client arguments are invalid',
+    });
+  }
+  return error;
+}
+
+function inputError(kind) {
+  return new RelayClientError({
+    kind,
+    message: kind === 'configuration'
+      ? 'Relay client configuration is invalid'
+      : 'Relay client arguments are invalid',
+  });
+}
+
+function chargeString(value, budget, kind) {
+  budget.stringBytes += Buffer.byteLength(value, 'utf8');
+  if (budget.stringBytes > MAX_JSON_STRING_BYTES) throw inputError(kind);
+}
+
+function cloneJson(value, budget, depth, allowUndefined, kind) {
+  if (depth > MAX_JSON_DEPTH) throw inputError(kind);
+  budget.nodes += 1;
+  if (budget.nodes > MAX_JSON_NODES) throw inputError(kind);
+
+  if (value === undefined) {
+    if (allowUndefined) return undefined;
+    throw inputError(kind);
+  }
+  if (value === null || typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    chargeString(value, budget, kind);
+    return value;
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw inputError(kind);
+    return value;
+  }
+  if (typeof value !== 'object' || isProxy(value)) throw inputError(kind);
+
+  const prototype = Object.getPrototypeOf(value);
+  const array = Array.isArray(value);
+  if (array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) {
+    throw inputError(kind);
+  }
+  if (budget.active.has(value)) throw inputError(kind);
+  budget.active.add(value);
+
+  try {
+    const keys = Reflect.ownKeys(value);
+    if (keys.some((key) => typeof key === 'symbol')) throw inputError(kind);
+
+    if (array) {
+      if (value.length + budget.nodes > MAX_JSON_NODES) throw inputError(kind);
+      const clone = new Array(value.length);
+      let elementCount = 0;
+      for (const key of keys) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !Object.hasOwn(descriptor, 'value')) throw inputError(kind);
+        if (key === 'length') continue;
+        chargeString(key, budget, kind);
+        const index = Number(key);
+        if (!descriptor.enumerable || !Number.isInteger(index) || index < 0
+          || index >= value.length || String(index) !== key) {
+          throw inputError(kind);
+        }
+        clone[index] = cloneJson(descriptor.value, budget, depth + 1, false, kind);
+        elementCount += 1;
+      }
+      if (elementCount !== value.length) throw inputError(kind);
+      return clone;
+    }
+
+    const clone = Object.create(null);
+    for (const key of keys) {
+      chargeString(key, budget, kind);
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor || !Object.hasOwn(descriptor, 'value')) throw inputError(kind);
+      if (!descriptor.enumerable) continue;
+      clone[key] = cloneJson(descriptor.value, budget, depth + 1, false, kind);
+    }
+    return clone;
+  } finally {
+    budget.active.delete(value);
+  }
+}
+
+function cloneArguments(args, kind, requiredJsonArguments = new Set()) {
+  const budget = { nodes: 0, stringBytes: 0, active: new WeakSet() };
+  return args.map((value, index) => (
+    cloneJson(value, budget, 0, !requiredJsonArguments.has(index), kind)
+  ));
+}
+
+function wrapAsync(prototype, name, requiredJsonArguments) {
+  const original = prototype[name];
+  prototype[name] = function (...args) {
+    try {
+      const clonedArgs = cloneArguments(args, 'invalid_request', requiredJsonArguments);
+      return original.apply(this, clonedArgs).catch((error) => { throw normalize(error); });
+    } catch (error) {
+      throw normalize(error, 'invalid_request');
+    }
+  };
+}
+
+const METHODS = [
+  'health', 'ready', 'openapi', 'serviceMetadata', 'resources', 'continueResources', 'resource',
+  'listRecords', 'continueListRecords', 'readRecord', 'lookup', 'search', 'continueSearch',
+  'artifact', 'sdmxData', 'sdmxStructure',
+];
+const REQUIRED_JSON_ARGUMENTS = {
+  continueResources: new Set([0]),
+  continueListRecords: new Set([0]),
+  lookup: new Set([2]),
+  search: new Set([2]),
+  continueSearch: new Set([0]),
+  sdmxData: new Set([0]),
+  sdmxStructure: new Set([0]),
+};
+for (const method of METHODS) {
+  wrapAsync(native.RelayClient.prototype, method, REQUIRED_JSON_ARGUMENTS[method]);
+}
+
+class RelayClient extends native.RelayClient {
+  constructor(config) {
+    try {
+      super(...cloneArguments([config], 'configuration', new Set([0])));
+    } catch (error) {
+      throw normalize(error, 'configuration');
+    }
+  }
+}
+
+module.exports = { RelayClient, RelayClientError };

package/relay/index.d.ts

@@ -0,0 +1,58 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+export declare class RelayClient {
+  constructor(configValue: any)
+  health(): Promise<CompleteOutcome>
+  ready(): Promise<CompleteOutcome>
+  openapi(etag?: string | undefined | null): Promise<RawCompleteOutcome | NotModifiedOutcome>
+  serviceMetadata(etag?: string | undefined | null): Promise<CompleteOutcome | NotModifiedOutcome>
+  resources(options?: any | undefined | null, etag?: string | undefined | null): Promise<ResourcePageOutcome | NotModifiedOutcome>
+  continueResources(continuation: any, etag?: string | undefined | null): Promise<ResourcePageOutcome | NotModifiedOutcome>
+  resource(resource: string, etag?: string | undefined | null): Promise<CompleteOutcome | NotModifiedOutcome>
+  listRecords(resource: string, options?: any | undefined | null, etag?: string | undefined | null): Promise<CollectionPageOutcome | NotModifiedOutcome>
+  continueListRecords(continuation: any, etag?: string | undefined | null): Promise<CollectionPageOutcome | NotModifiedOutcome>
+  readRecord(resource: string, recordIdentifier: string, options?: any | undefined | null, etag?: string | undefined | null): Promise<CompleteOutcome | NotModifiedOutcome>
+  lookup(resource: string, lookup: string, selectors: any, options?: any | undefined | null, etag?: string | undefined | null): Promise<CompleteOutcome | NotModifiedOutcome>
+  search(resource: string, search: string, options: any, etag?: string | undefined | null): Promise<CollectionPageOutcome | NotModifiedOutcome>
+  continueSearch(continuation: any, etag?: string | undefined | null): Promise<CollectionPageOutcome | NotModifiedOutcome>
+  artifact(artifactIdentifier: string, etag?: string | undefined | null): Promise<RawCompleteOutcome | NotModifiedOutcome>
+  sdmxData(requestValue: any, etag?: string | undefined | null): Promise<RawCompleteOutcome | NotModifiedOutcome>
+  sdmxStructure(requestValue: any, etag?: string | undefined | null): Promise<RawCompleteOutcome | NotModifiedOutcome>
+}
+
+export interface CollectionPageOutcome {
+  kind: string
+  value: any
+  continuation?: any
+  traceId: string
+  etag?: string
+}
+
+export interface CompleteOutcome {
+  kind: string
+  value: any
+  traceId: string
+  etag?: string
+}
+
+export interface NotModifiedOutcome {
+  kind: string
+  etag: string
+  traceId: string
+}
+
+export interface RawCompleteOutcome {
+  kind: string
+  body: Buffer
+  mediaType: string
+  traceId: string
+  etag?: string
+}
+
+export interface ResourcePageOutcome {
+  kind: string
+  value: any
+  continuation?: any
+  traceId: string
+  etag?: string
+}

package/relay/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('../native').load('relay');