@registrystack/client 0.37.0 → 0.38.0

package/README.md

@@ -1,7 +1,7 @@
 # @registrystack/client
 
 One versioned Node.js package for the Discovery, Evidence, Relay, Base Registry
-Engine, and Casework client APIs in Registry Stack.
+Engine, Casework, and Messaging client APIs in Registry Stack.
 
 ## Install
 
@@ -11,13 +11,13 @@ npm install "@registrystack/client@<version>"
 
 Requires Node.js 22.12 or newer. Supported targets are macOS arm64, Linux
 arm64 with glibc, and Linux x64 with glibc; installing the package pulls in
-one platform-specific optional dependency containing all five native
+one platform-specific optional dependency containing all six native
 bindings.
 
 ## Usage
 
 ```js
-const { discovery, evidence, relay, breg, casework } = require('@registrystack/client');
+const { discovery, evidence, relay, breg, casework, messaging } = require('@registrystack/client');
 
 const registry = new breg.BaseRegistryClient({
   baseUrl: 'https://registry.example.invalid/',
@@ -25,6 +25,9 @@ const registry = new breg.BaseRegistryClient({
 const work = new casework.CaseworkClient({
   baseUrl: 'https://casework.example.invalid/',
 });
+const messages = new messaging.MessagingClient({
+  baseUrl: 'https://messaging.example.invalid/',
+});
 ```
 
 ## Products
@@ -38,6 +41,8 @@ const work = new casework.CaseworkClient({
   applied-request result navigation.
 - `casework`: Registry Casework, staff inbox, claims, drafts, decisions,
   recovery, history, holdings, and directory bootstrap.
+- `messaging`: Registry Messaging, submit, inspect, cancel, and preview
+  institution-owned messages.
 
 Each product remains in its own namespace because its routing,
 authentication, errors, and verification rules are different.
@@ -99,6 +104,9 @@ is active.
 The `casework` namespace is part of the unified package beginning with
 Registry Stack v0.30.0.
 
+The `messaging` namespace is part of the unified package beginning with
+Registry Stack v0.38.0.
+
 ## Casework notes
 
 The Casework module is for a trusted server host. Each call takes that request's

package/index.d.ts

@@ -3,5 +3,6 @@ import * as evidence from './evidence/client'
 import * as relay from './relay/client'
 import * as breg from './breg/client'
 import * as casework from './casework/client'
+import * as messaging from './messaging/client'
 
-export { discovery, evidence, relay, breg, casework }
+export { discovery, evidence, relay, breg, casework, messaging }

package/index.js

@@ -2,9 +2,10 @@
 
 // One assignment per namespace, never a `module.exports` object literal: Node
 // scans this file for these statements to synthesise the named exports an ESM
-// consumer imports, and `require()` sees the same five properties either way.
+// consumer imports, and `require()` sees the same six properties either way.
 exports.discovery = require('./discovery/client');
 exports.evidence = require('./evidence/client');
 exports.relay = require('./relay/client');
 exports.breg = require('./breg/client');
 exports.casework = require('./casework/client');
+exports.messaging = require('./messaging/client');

package/messaging/client.d.ts

@@ -0,0 +1,143 @@
+/** An integer for which `Number.isSafeInteger` is true. */
+export type SafeInteger = number
+/** A lowercase hyphenated UUID, checked by the native binding before any request is sent. */
+export type MessageId = string
+/** An RFC 3339 instant, parsed by the runtime. */
+export type Instant = string
+export type JsonScalar = string | number | boolean | null
+export type JsonValue = JsonScalar | ReadonlyArray<JsonValue> | { readonly [key: string]: JsonValue }
+
+export interface MessagingClientConfig {
+  baseUrl: string
+  requestTimeoutMilliseconds?: SafeInteger | null
+  connectTimeoutMilliseconds?: SafeInteger | null
+  maxResponseBytes?: SafeInteger | null
+  userAgent?: string | null
+  trustedRootCertificates?: string | null
+}
+
+export type Channel = 'email' | 'sms'
+export type MessageStatus = 'queued' | 'sending' | 'submitted' | 'delivered' | 'failed' | 'expired' | 'cancelled' | 'unknown'
+export type MessageDispatch = 'queued' | 'sending' | 'submitted' | 'failed' | 'unknown' | 'cancelled' | 'expired'
+export type MessageReport = 'none' | 'sent' | 'delivered' | 'undelivered' | 'unavailable'
+export type AttemptOutcome = 'in-progress' | 'accepted' | 'transient' | 'permanent' | 'maybe-sent' | 'interrupted'
+
+/** Exactly one email address or one E.164 phone number. */
+export type Recipient = { email: string; phone?: never } | { phone: string; email?: never }
+export interface TemplateReference { id: string; version: string }
+export interface DirectContent { subject?: string; text: string }
+
+/** Exactly one of `template` or `content`; `locale` and `data` accompany a template. */
+export interface SubmitMessageRequest {
+  senderProfile: string
+  to: Recipient
+  template?: TemplateReference
+  locale?: string
+  data?: JsonValue
+  content?: DirectContent
+  notBefore?: Instant
+  expiresAt?: Instant
+  correlationId?: string
+}
+
+export interface MessageLinks { self: string; cancel: string }
+export interface MessageReceipt { id: MessageId; status: MessageStatus; links: MessageLinks }
+export interface AttemptSummary {
+  generation: SafeInteger
+  attempt: SafeInteger
+  outcome: AttemptOutcome
+  startedAt: Instant
+  finishedAt?: Instant
+  providerReference: boolean
+}
+export interface MessageView {
+  id: MessageId
+  status: MessageStatus
+  dispatch: MessageDispatch
+  report: MessageReport
+  reportedAt?: Instant
+  channel: Channel
+  senderProfile: string
+  to: Recipient
+  template?: TemplateReference
+  correlationId?: string
+  acceptedAt: Instant
+  notBefore?: Instant
+  expiresAt: Instant
+  updatedAt: Instant
+  attempts: ReadonlyArray<AttemptSummary>
+  links: MessageLinks
+}
+
+export interface TemplatePreviewRequest { locale: string; data: JsonValue }
+export type SmsEncoding = 'gsm7' | 'ucs2'
+/** Septets for GSM-7, UTF-16 code units for UCS-2. */
+export interface SegmentCount { encoding: SmsEncoding; units: SafeInteger; segments: SafeInteger }
+export interface RenderedParts { subject?: string; text: string; html?: string }
+export interface TemplatePreview {
+  template: TemplateReference
+  locale: string
+  channel: Channel
+  packageDigest: string
+  parts: RenderedParts
+  sms?: SegmentCount
+}
+
+export interface MessagingOutcome<T> { kind: 'complete'; value: T; traceId: string }
+
+/** The closed catalogue: the client answers any other code as a protocol failure. */
+export type MessagingProblemCode =
+  | 'authentication.refused'
+  | 'callback.unreadable'
+  | 'callback.unverified'
+  | 'content.invalid'
+  | 'content.too-large'
+  | 'content.too-many-segments'
+  | 'idempotency.expired'
+  | 'idempotency.key-reused'
+  | 'message.dispatch-started'
+  | 'message.not-visible'
+  | 'message.terminal'
+  | 'operation.not-authorized'
+  | 'profile.not-authorized'
+  | 'quota.exceeded'
+  | 'rate-limit.exceeded'
+  | 'request.body-too-large'
+  | 'request.invalid'
+  | 'request.method-not-allowed'
+  | 'request.not-found'
+  | 'request.unprocessable'
+  | 'request.unsupported-media-type'
+  | 'service.unavailable'
+  | 'template.data-invalid'
+  | 'template.locale-unavailable'
+  | 'template.not-found'
+  | 'template.render-refused'
+export type MessagingProtocolFailure = 'header_bounds' | 'trace_context' | 'media_type' | 'body' | 'problem' | 'status' | 'protocol'
+
+export class MessagingClientError extends Error {
+  readonly kind: 'configuration' | 'invalid_request' | 'transport' | 'problem' | 'protocol'
+  readonly code?: MessagingProblemCode
+  readonly title?: string
+  readonly detail?: string
+  readonly status?: SafeInteger
+  readonly traceId?: string
+  /**
+   * Whole seconds a 429 limit refusal asked the caller to wait, from
+   * `Retry-After`, at most one day. Absent on every other failure; the
+   * client never waits or retries itself.
+   */
+  readonly retryAfterSeconds?: SafeInteger
+  readonly transportKind?: string
+  readonly protocolFailure?: MessagingProtocolFailure
+}
+
+export class MessagingClient {
+  constructor(config: MessagingClientConfig)
+  health(): Promise<MessagingOutcome<null>>
+  ready(): Promise<MessagingOutcome<null>>
+  submit(token: string, idempotencyKey: string, request: SubmitMessageRequest): Promise<MessagingOutcome<MessageReceipt>>
+  message(token: string, messageId: MessageId): Promise<MessagingOutcome<MessageView>>
+  cancel(token: string, messageId: MessageId): Promise<MessagingOutcome<MessageView>>
+  preview(token: string, templateId: string, version: string, request: TemplatePreviewRequest): Promise<MessagingOutcome<TemplatePreview>>
+}

package/messaging/client.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const { types: { isProxy } } = require('node:util');
+const native = require('./index');
+
+const MAX_JSON_DEPTH = 64;
+const MAX_JSON_NODES = 20_000;
+const MAX_JSON_STRING_BYTES = 1024 * 1024;
+
+class MessagingClientError extends Error {
+  constructor(envelope) {
+    super(envelope.message);
+    this.name = 'MessagingClientError';
+    this.kind = envelope.kind;
+    for (const field of ['code', 'title', 'detail', 'status', 'traceId', 'retryAfterSeconds', 'transportKind', 'protocolFailure']) {
+      if (envelope[field] !== undefined && envelope[field] !== null) this[field] = envelope[field];
+    }
+  }
+}
+
+function normalized(error, fallbackKind) {
+  if (error instanceof MessagingClientError) return error;
+  if (error instanceof Error && typeof error.message === 'string') {
+    try {
+      const envelope = JSON.parse(error.message);
+      if (envelope && typeof envelope.kind === 'string') return new MessagingClientError(envelope);
+    } catch {
+      // napi argument conversion errors have no mapped envelope.
+    }
+  }
+  if (fallbackKind) {
+    return new MessagingClientError({
+      kind: fallbackKind,
+      message: fallbackKind === 'configuration'
+        ? 'Messaging client configuration is invalid'
+        : 'Messaging client arguments are invalid',
+    });
+  }
+  return error;
+}
+
+function cloneJson(value, budget, depth) {
+  if (depth > MAX_JSON_DEPTH || ++budget.nodes > MAX_JSON_NODES) throw normalized({}, 'invalid_request');
+  if (value === null || typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    budget.bytes += Buffer.byteLength(value, 'utf8');
+    if (budget.bytes > MAX_JSON_STRING_BYTES) throw normalized({}, 'invalid_request');
+    return value;
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))) {
+      throw normalized({}, 'invalid_request');
+    }
+    return value;
+  }
+  if (value === undefined || typeof value !== 'object' || isProxy(value)) {
+    throw normalized({}, 'invalid_request');
+  }
+  const array = Array.isArray(value);
+  const prototype = Object.getPrototypeOf(value);
+  if (array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) {
+    throw normalized({}, 'invalid_request');
+  }
+  if (budget.active.has(value)) throw normalized({}, 'invalid_request');
+  budget.active.add(value);
+  try {
+    if (array) return value.map((member) => cloneJson(member, budget, depth + 1));
+    const result = Object.create(null);
+    for (const key of Reflect.ownKeys(value)) {
+      if (typeof key !== 'string') throw normalized({}, 'invalid_request');
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor || !Object.hasOwn(descriptor, 'value')) throw normalized({}, 'invalid_request');
+      if (descriptor.enumerable) {
+        budget.bytes += Buffer.byteLength(key, 'utf8');
+        if (budget.bytes > MAX_JSON_STRING_BYTES) throw normalized({}, 'invalid_request');
+        result[key] = cloneJson(descriptor.value, budget, depth + 1);
+      }
+    }
+    return result;
+  } finally {
+    budget.active.delete(value);
+  }
+}
+
+function sanitize(value) {
+  return cloneJson(value, { nodes: 0, bytes: 0, active: new WeakSet() }, 0);
+}
+
+const NativeMessagingClient = native.MessagingClient;
+
+class MessagingClient {
+  constructor(config) {
+    try {
+      this.native = new NativeMessagingClient(sanitize(config));
+    } catch (error) {
+      throw normalized(error, 'configuration');
+    }
+  }
+}
+
+for (const [method, jsonIndexes] of [
+  ['health', []],
+  ['ready', []],
+  ['submit', [2]],
+  ['message', []],
+  ['cancel', []],
+  ['preview', [3]],
+]) {
+  MessagingClient.prototype[method] = function (...args) {
+    try {
+      for (const index of jsonIndexes) {
+        if (args[index] !== undefined && args[index] !== null) args[index] = sanitize(args[index]);
+      }
+      return this.native[method](...args).catch((error) => { throw normalized(error); });
+    } catch (error) {
+      throw normalized(error, 'invalid_request');
+    }
+  };
+}
+
+module.exports = { MessagingClient, MessagingClientError };

package/messaging/index.d.ts

@@ -0,0 +1,27 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+
+export declare class MessagingClient {
+  constructor(config: MessagingClientConfig)
+  health(): Promise<MessagingOutcome>
+  ready(): Promise<MessagingOutcome>
+  submit(token: string, idempotencyKey: string, request: any): Promise<MessagingOutcome>
+  message(token: string, messageId: string): Promise<MessagingOutcome>
+  cancel(token: string, messageId: string): Promise<MessagingOutcome>
+  preview(token: string, templateId: string, version: string, request: any): Promise<MessagingOutcome>
+}
+
+export interface MessagingClientConfig {
+  baseUrl: string
+  requestTimeoutMilliseconds?: number
+  connectTimeoutMilliseconds?: number
+  maxResponseBytes?: number
+  userAgent?: string
+  trustedRootCertificates?: string
+}
+
+export interface MessagingOutcome {
+  kind: string
+  value: any
+  traceId: string
+}

package/messaging/index.js

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

package/native.js

@@ -1,7 +1,7 @@
 'use strict';
 
-const PACKAGE_VERSION = '0.37.0';
-const PRODUCTS = new Set(['discovery', 'evidence', 'relay', 'breg', 'casework']);
+const PACKAGE_VERSION = '0.38.0';
+const PRODUCTS = new Set(['discovery', 'evidence', 'relay', 'breg', 'casework', 'messaging']);
 
 function target() {
   if (process.platform === 'darwin' && process.arch === 'arm64') return 'darwin-arm64';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@registrystack/client",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Unified Node.js client for Registry Stack products.",
   "license": "Apache-2.0",
   "homepage": "https://docs.registrystack.org/reference/client-api/",
@@ -14,7 +14,8 @@
     "evidence",
     "relay",
     "breg",
-    "casework"
+    "casework",
+    "messaging"
   ],
   "publishConfig": {
     "access": "public",
@@ -41,7 +42,8 @@
     "evidence",
     "relay",
     "breg",
-    "casework"
+    "casework",
+    "messaging"
   ],
   "engines": {
     "node": ">=22.12.0"
@@ -57,8 +59,8 @@
     "typescript": "6.0.3"
   },
   "optionalDependencies": {
-    "@registrystack/client-darwin-arm64": "0.37.0",
-    "@registrystack/client-linux-arm64-gnu": "0.37.0",
-    "@registrystack/client-linux-x64-gnu": "0.37.0"
+    "@registrystack/client-darwin-arm64": "0.38.0",
+    "@registrystack/client-linux-arm64-gnu": "0.38.0",
+    "@registrystack/client-linux-x64-gnu": "0.38.0"
   }
 }