@heavybit/shared-lib 2.1.0 → 2.7.0

package/dist/types/approvals/index.d.ts

@@ -0,0 +1,99 @@
+import type { AuthUser } from '../types/index.js';
+/**
+ * Two-person approval state machine. A requester asks for a sensitive operation; a different person who
+ * holds both the operation's permission and the app's "decide" permission approves or rejects it; the
+ * approved operation is then executed once (or fails). Pending requests expire after a TTL.
+ *
+ * ```
+ * pending ──► approved ──► executed
+ *    │            └──────► failed
+ *    ├──► rejected
+ *    ├──► cancelled
+ *    └──► expired
+ * ```
+ *
+ * App values (the decide permission and the TTL) are passed in through {@link createApprovalPolicy}.
+ */
+/** Every approval state. */
+export declare const APPROVAL_STATES: readonly ["pending", "approved", "rejected", "cancelled", "expired", "executed", "failed"];
+/** One approval state. */
+export type ApprovalState = (typeof APPROVAL_STATES)[number];
+/** The approval facts the checks need. */
+export interface ApprovalSubject {
+    state: ApprovalState;
+    requesterUserId: string;
+    /** Permission needed to perform the operation itself, e.g. `payouts.manage`. */
+    operationPermission: string;
+    /** When a pending request stops being decidable (omit for no expiry). */
+    expiresAt?: Date | string | null;
+}
+/** The caller deciding or cancelling. */
+export type ApprovalActor = Pick<AuthUser, 'id' | 'permissions' | 'isSuperAdmin'>;
+/**
+ * True when `from → to` is an allowed move.
+ *
+ * @example canTransition('pending', 'approved') // true
+ */
+export declare function canTransition(from: ApprovalState, to: ApprovalState): boolean;
+/**
+ * Throws unless `from → to` is allowed.
+ *
+ * @throws ConflictError (`APPROVAL_INVALID_TRANSITION`).
+ */
+export declare function assertTransition(from: ApprovalState, to: ApprovalState): void;
+/** True when the state allows no further moves. */
+export declare function isTerminalApprovalState(state: ApprovalState): boolean;
+/**
+ * Throws unless `approver` may approve or reject `approval`: it is pending and not expired, the approver
+ * is not the requester (even a super admin cannot approve their own request), and holds both the
+ * operation permission and `decidePermission`.
+ *
+ * @param approval The request.
+ * @param approver The deciding user.
+ * @param decidePermission The app's "may decide approvals" permission.
+ * @param now Clock (tests).
+ * @throws ConflictError (`APPROVAL_NOT_PENDING`, `APPROVAL_EXPIRED`) or ForbiddenError
+ *   (`APPROVAL_SELF_DECISION`, `APPROVAL_FORBIDDEN`).
+ */
+export declare function assertCanDecide(approval: ApprovalSubject, approver: ApprovalActor, decidePermission: string, now?: Date): void;
+/**
+ * Throws unless `user` may cancel `approval`: only the requester, and only while it is pending.
+ *
+ * @throws ConflictError (`APPROVAL_NOT_PENDING`) or ForbiddenError (`APPROVAL_NOT_REQUESTER`).
+ */
+export declare function assertCanCancel(approval: ApprovalSubject, user: Pick<AuthUser, 'id'>): void;
+/**
+ * When a request made at `from` expires.
+ *
+ * @param ttlSeconds Positive lifetime in seconds.
+ * @param from Creation time (default now).
+ * @returns The expiry instant.
+ * @example approvalExpiresAt(3600, new Date('2026-01-01T00:00:00Z')) // 2026-01-01T01:00:00Z
+ */
+export declare function approvalExpiresAt(ttlSeconds: number, from?: Date): Date;
+/** App settings for {@link createApprovalPolicy}. */
+export interface ApprovalPolicyOptions {
+    /** Permission every approver must hold in addition to the operation's permission. */
+    decidePermission: string;
+    /** Lifetime of a pending request, in seconds. */
+    ttlSeconds: number;
+}
+/** The approval rules bound to one app's decide permission and TTL. */
+export interface ApprovalPolicy {
+    readonly decidePermission: string;
+    readonly ttlSeconds: number;
+    canTransition: typeof canTransition;
+    assertTransition: typeof assertTransition;
+    assertCanDecide(approval: ApprovalSubject, approver: ApprovalActor, now?: Date): void;
+    assertCanCancel: typeof assertCanCancel;
+    expiresAt(from?: Date): Date;
+}
+/**
+ * Binds the approval rules to an app's decide permission and TTL.
+ *
+ * @param options Decide permission and TTL.
+ * @returns The bound policy.
+ * @example const approvals = createApprovalPolicy({ decidePermission: 'requests.decide', ttlSeconds: 86_400 });
+ */
+export declare function createApprovalPolicy(options: ApprovalPolicyOptions): ApprovalPolicy;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/approvals/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/approvals/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AAEH,4BAA4B;AAC5B,eAAO,MAAM,eAAe,4FAA6F,CAAC;AAE1H,0BAA0B;AAC1B,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAY7D,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yEAAyE;IACzE,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,yCAAyC;AACzC,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,aAAa,GAAG,cAAc,CAAC,CAAC;AAElF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,aAAa,GAAG,OAAO,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,aAAa,GAAG,IAAI,CAI7E;AAED,mDAAmD;AACnD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAErE;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,IAAI,CAQ1I;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,IAAI,CAO3F;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,IAAI,CAGnF;AAED,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACpC,qFAAqF;IACrF,gBAAgB,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,gBAAgB,EAAE,OAAO,gBAAgB,CAAC;IAC1C,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACtF,eAAe,EAAE,OAAO,eAAe,CAAC;IACxC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAYnF"}

package/dist/types/audit/index.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Business audit events: who did what to which entity, in which scope, and which fields changed. Each
+ * service builds the event here and stages it through its outbox for the audit store; the app's contracts
+ * map it to its own event payload. Secrets never reach the event: keys matching the redaction list are
+ * dropped (only their names are kept), and phone-like values are masked.
+ */
+/** The tenant or other scope the audited entity belongs to, e.g. `{ key: 'tenant', id: '01J…' }`. */
+export interface AuditScope {
+    key: string;
+    id: string;
+}
+/** Whoever performed the action; `null` (or an absent id) means the system. */
+export interface AuditActor {
+    id: string | null;
+}
+/** One changed field: its value before and after (null when absent). */
+export interface AuditChange {
+    before: unknown;
+    after: unknown;
+}
+/** Input to {@link buildAuditEvent}. */
+export interface AuditEventInput {
+    /** What happened, as a dotted verb, e.g. `widget.price.changed`. */
+    action: string;
+    entityType: string;
+    entityId: string | null;
+    scope: AuditScope | null;
+    actor: AuditActor | null;
+    /** Entity state before the action (`null` on create). */
+    before?: Record<string, unknown> | null;
+    /** Entity state after the action (`null` on delete). */
+    after?: Record<string, unknown> | null;
+    ip?: string | null;
+    userAgent?: string | null;
+    outcome?: AuditOutcome;
+    /** When it happened; defaults to now. */
+    occurredAt?: Date | string | number;
+}
+/** Whether the audited action succeeded. */
+export type AuditOutcome = 'success' | 'failure';
+/** The built event: app-neutral, ready for an app binding to map onto its event payload. */
+export interface AuditEvent {
+    action: string;
+    entityType: string;
+    entityId: string | null;
+    scope: AuditScope | null;
+    actorUserId: string | null;
+    outcome: AuditOutcome;
+    occurredAt: string;
+    /** Only the fields whose value changed (deep comparison), secrets excluded. */
+    changes: Record<string, AuditChange>;
+    /** Names of changed fields whose values were dropped because they match the redaction list. */
+    redactedFields: string[];
+    ip: string | null;
+    /** Truncated to {@link MAX_USER_AGENT_LENGTH} characters. */
+    userAgent: string | null;
+}
+/** Options for {@link createAuditEventBuilder}. */
+export interface AuditEventBuilderOptions {
+    /** Extra key words to drop, on top of the logger's default redaction list (`password`, `token`, …). */
+    redactKeys?: readonly string[];
+}
+/** User-agent strings are cut to this length. */
+export declare const MAX_USER_AGENT_LENGTH = 255;
+/**
+ * Creates an audit-event builder with the app's extra redaction words.
+ *
+ * @param options Extra redaction words.
+ * @returns `buildAuditEvent` bound to that list.
+ * @example const buildAudit = createAuditEventBuilder({ redactKeys: ['nationalId'] });
+ */
+export declare function createAuditEventBuilder(options?: AuditEventBuilderOptions): (input: AuditEventInput) => AuditEvent;
+/**
+ * Builds an audit event with the default redaction list: the diff holds only changed fields; secret
+ * fields are dropped (named in `redactedFields`); phone fields are masked to their last 4 digits.
+ *
+ * @param input Action, entity, scope, actor, before/after state and request facts.
+ * @returns The event.
+ * @example buildAuditEvent({ action: 'widget.updated', entityType: 'widget', entityId, scope: { key: 'tenant', id: tenantId }, actor: req.user ?? null, before, after, ip: req.ip, userAgent: req.get('user-agent') })
+ */
+export declare const buildAuditEvent: (input: AuditEventInput) => AuditEvent;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/audit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/audit/index.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,qGAAqG;AACrG,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CACnB;AAED,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,yCAAyC;IACzC,UAAU,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;CACrC;AAED,4CAA4C;AAC5C,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;AAEjD,4FAA4F;AAC5F,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrC,+FAA+F;IAC/F,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,mDAAmD;AACnD,MAAM,WAAW,wBAAwB;IACvC,uGAAuG;IACvG,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,iDAAiD;AACjD,eAAO,MAAM,qBAAqB,MAAM,CAAC;AA+BzC;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,wBAA6B,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,UAAU,CAmBtH;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,UAAsC,CAAC"}

package/dist/types/cache/index.d.ts

@@ -1,45 +1,95 @@
 import { Redis, type RedisOptions } from 'ioredis';
 import type { Logger } from '../types/index.js';
+import type { RedisKey, RedisKeyspace } from './keyspace.js';
+export * from './keyspace.js';
+/** Per-write options: required TTL and optional invalidation tags. */
 export interface CacheSetOptions {
-    ttlSec?: number;
+    /** Time to live in whole seconds; required and must be > 0 (every Redis key gets a TTL). */
+    ttlSec: number;
     /** Tags let one call invalidate every key derived from an entity (e.g. `user:01J…`). */
     tags?: string[];
 }
+/** Cache-aside store. Keys come only from the cache's {@link RedisKeyspace}; there are no KEYS/FLUSH helpers. */
 export interface Cache {
-    get<T>(key: string): Promise<T | undefined>;
-    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
-    del(...keys: string[]): Promise<void>;
+    /** Reads a value; `undefined` on a miss. */
+    get<T>(key: RedisKey): Promise<T | undefined>;
+    /** Stores a value for `ttlSec` seconds. */
+    set<T>(key: RedisKey, value: T, options: CacheSetOptions): Promise<void>;
+    /** Deletes keys (Redis and the in-memory fallback). */
+    del(...keys: RedisKey[]): Promise<void>;
     /** Cache-aside: returns the cached value or loads, stores and returns it. Concurrent misses share one load. */
-    wrap<T>(key: string, loader: () => Promise<T>, options?: CacheSetOptions & {
+    wrap<T>(key: RedisKey, loader: () => Promise<T>, options: CacheSetOptions & {
         cacheNull?: boolean;
     }): Promise<T>;
+    /** Deletes every key stored with any of `tags`. */
     invalidateTags(...tags: string[]): Promise<void>;
 }
+/** Inputs to {@link createCache}. */
 export interface CacheOptions {
     /** Null → in-memory only (tests, local tooling). */
     redis: Redis | null;
-    /** Key namespace, e.g. `auth` → keys `auth:<key>`. Combine with the client-level env prefix. */
-    namespace: string;
-    defaultTtlSec?: number;
+    /** The service keyspace; every key passed in must come from it, and tag sets live under it. */
+    keyspace: RedisKeyspace;
     /** Upper bound for the in-memory layer / fallback. */
     memoryMaxEntries?: number;
     logger?: Logger;
 }
+/** Purpose segment for tag index sets: `{prefix}cache-tag:{tag}`. */
+export declare const CACHE_TAG_PURPOSE = "cache-tag";
+/**
+ * Throws unless `ttlSec` is a positive whole number of seconds.
+ *
+ * @param ttlSec Proposed TTL.
+ * @throws ConfigError for ttl ≤ 0, fractions, NaN or Infinity.
+ * @example assertTtl(60)
+ */
+export declare function assertTtl(ttlSec: number): void;
 /**
  * Redis-backed cache with tag invalidation. If Redis errors, reads fall through to the loader
  * and writes go to a bounded in-memory store, so a cache outage degrades latency rather than
  * availability.
+ *
+ * @param options Redis client (or null for memory only), the service keyspace, memory bound, logger.
+ * @returns The {@link Cache}.
+ * @example
+ * const cache = createCache({ redis, keyspace: ks, logger });
+ * const widget = await cache.wrap(ks.key('widget', id), () => repo.find(id), { ttlSec: 300 });
  */
 export declare function createCache(options: CacheOptions): Cache;
+/** Connection settings for {@link createRedisClient} (the parsed `redisEnv` block fits). */
+export interface RedisConnectionEnv {
+    REDIS_URL?: string;
+    REDIS_HOST?: string;
+    REDIS_PORT?: number;
+    REDIS_PASSWORD?: string;
+    REDIS_DB?: number;
+}
+/** Extra inputs to {@link createRedisClient}. */
 export interface RedisClientOptions {
-    url?: string;
-    db?: number;
-    /** Prepended to every key by ioredis, e.g. `myapp:prod:`. */
-    keyPrefix?: string;
     logger?: Logger;
+    /** Extra ioredis options. `keyPrefix` is always cleared: the keyspace does the prefixing. */
     options?: RedisOptions;
 }
-/** ioredis client that never crashes the process on connection errors and retries forever. */
-export declare function createRedisClient(opts: RedisClientOptions): Redis;
+/**
+ * ioredis client that never crashes the process on connection errors and retries forever.
+ * It sets no `keyPrefix`: keys carry their full `{app}:{env}:{service}:` prefix from the keyspace.
+ *
+ * @param env Connection env (`REDIS_URL`, or host/port/password, and `REDIS_DB`).
+ * @param opts Logger and extra ioredis options.
+ * @returns The client.
+ * @example const redis = createRedisClient(config, { logger });
+ */
+export declare function createRedisClient(env: RedisConnectionEnv, opts?: RedisClientOptions): Redis;
+/**
+ * `SET key value EX ttlSec` for a keyspace key; refuses a TTL ≤ 0 so no key lives forever.
+ *
+ * @param redis Client (or anything with a compatible `set`).
+ * @param key Key from the service keyspace.
+ * @param value String value.
+ * @param ttlSec TTL in whole seconds (> 0).
+ * @throws ConfigError for an invalid TTL.
+ * @example await setWithTtl(redis, ks.key('session', id), payload, 900);
+ */
+export declare function setWithTtl(redis: Pick<Redis, 'set'>, key: RedisKey, value: string, ttlSec: number): Promise<void>;
 export type { Redis };
 //# sourceMappingURL=index.d.ts.map

package/dist/types/cache/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAEnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,KAAK;IACpB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC5C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,GAAG,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,+GAA+G;IAC/G,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChH,cAAc,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,gGAAgG;IAChG,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA+BD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CA+FxD;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,KAAK,CAmBjE;AAED,YAAY,EAAE,KAAK,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE7D,cAAc,eAAe,CAAC;AAE9B,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,4FAA4F;IAC5F,MAAM,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,iHAAiH;AACjH,MAAM,WAAW,KAAK;IACpB,4CAA4C;IAC5C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC9C,2CAA2C;IAC3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE,uDAAuD;IACvD,GAAG,CAAC,GAAG,IAAI,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,+GAA+G;IAC/G,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,GAAG;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjH,mDAAmD;IACnD,cAAc,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAED,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,+FAA+F;IAC/F,QAAQ,EAAE,aAAa,CAAC;IACxB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAI7C;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE9C;AAmCD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CAoGxD;AAED,4FAA4F;AAC5F,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,kBAAkB,EAAE,IAAI,GAAE,kBAAuB,GAAG,KAAK,CAsB/F;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvH;AAED,YAAY,EAAE,KAAK,EAAE,CAAC"}

package/dist/types/cache/keyspace.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Redis keyspace: every key is `{app}:{env}:{service}:{purpose}[:{part}…]`.
+ *
+ * One Redis installation may serve several apps and environments, so keys are namespaced by the app
+ * slug (a parameter — shared-lib names no app), the environment (`CACHE_KEY_PREFIX`) and the owning
+ * service. Build every key through {@link createRedisKeyspace}; never hand-write prefixes.
+ *
+ * Dependency-free (no ioredis), so it is exported from the package root as well as `/cache`.
+ */
+/** A key built by a {@link RedisKeyspace}. The brand stops hand-written strings reaching the cache helpers. */
+export type RedisKey = string & {
+    readonly __redisKey: true;
+};
+/** A value to hash before it goes into a key (personal data or secrets). Create with {@link sensitivePart}. */
+export interface SensitiveKeyPart {
+    readonly sensitive: string;
+}
+/** One variable part of a key. */
+export type RedisKeyPart = string | number | SensitiveKeyPart;
+/** Inputs to {@link createRedisKeyspace}. */
+export interface RedisKeyspaceOptions {
+    /** App slug, e.g. `myapp` (lower-case kebab-case). */
+    app: string;
+    /** Owning service (the service that writes the key), e.g. `widget-service`. */
+    service: string;
+    /** Environment segment, normally the `CACHE_KEY_PREFIX` env value (`dev`, `staging`, `prod`). */
+    env?: string;
+    /** Node environment used for the deployed-environment check (default `process.env.NODE_ENV`). */
+    nodeEnv?: string;
+    /** When set, hashed parts use HMAC-SHA256 with this secret instead of plain SHA-256. */
+    hashSecret?: string;
+}
+/** One service's key builder; every key it makes starts with {@link RedisKeyspace.prefix}. */
+export interface RedisKeyspace {
+    readonly app: string;
+    readonly env: string;
+    readonly service: string;
+    /** `{app}:{env}:{service}:` — every key and pattern starts with this. */
+    readonly prefix: string;
+    /**
+     * Builds `{prefix}{purpose}[:{part}…]`. Parts are percent-encoded so they cannot add segments or
+     * widen a SCAN pattern; long, email-like, phone-like and {@link sensitivePart} parts are hashed.
+     */
+    key(purpose: string, ...parts: RedisKeyPart[]): RedisKey;
+    /** SCAN pattern anchored on the prefix: `{prefix}{purpose}:{suffix}` (suffix defaults to `*`). */
+    pattern(purpose: string, suffix?: string): string;
+    /** True when `key` lies inside this keyspace. */
+    owns(key: string): key is RedisKey;
+}
+/** Environment segment used outside staging and production when none is given. */
+export declare const DEFAULT_KEY_ENV = "dev";
+/** Parts longer than this are hashed. */
+export declare const MAX_PLAIN_KEY_PART_LENGTH = 64;
+/** Marker that starts every hashed part. */
+export declare const HASHED_PART_PREFIX = "h.";
+/**
+ * Marks a key part as personal data or a secret so the keyspace always hashes it.
+ *
+ * @param value Raw value (e.g. an email address or a token).
+ * @returns A part the keyspace hashes.
+ * @example ks.key('otp', sensitivePart(email))
+ */
+export declare const sensitivePart: (value: string) => SensitiveKeyPart;
+/**
+ * Percent-encodes a plain key part, including the glob characters SCAN interprets.
+ *
+ * @param value Part text (non-empty).
+ * @returns The encoded part.
+ * @throws ConfigError when the part is empty.
+ * @example encodeKeyPart('a:b*') // 'a%3Ab%2A'
+ */
+export declare function encodeKeyPart(value: string): string;
+/**
+ * Creates the keyspace for one service.
+ *
+ * @param options App slug, service, env segment (`CACHE_KEY_PREFIX`), optional hash secret.
+ * @returns A {@link RedisKeyspace}.
+ * @throws ConfigError on an invalid segment, or when `env` is missing in staging/production.
+ * @example
+ * const ks = createRedisKeyspace({ app: 'myapp', service: 'widget-service', env: config.CACHE_KEY_PREFIX });
+ * ks.key('widget', widgetId) // 'myapp:prod:widget-service:widget:01J…'
+ */
+export declare function createRedisKeyspace(options: RedisKeyspaceOptions): RedisKeyspace;
+//# sourceMappingURL=keyspace.d.ts.map

package/dist/types/cache/keyspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyspace.d.ts","sourceRoot":"","sources":["../../../src/cache/keyspace.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,+GAA+G;AAC/G,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAA;CAAE,CAAC;AAE9D,+GAA+G;AAC/G,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,kCAAkC;AAClC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,gBAAgB,CAAC;AAE9D,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,8FAA8F;AAC9F,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,YAAY,EAAE,GAAG,QAAQ,CAAC;IACzD,kGAAkG;IAClG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAClD,iDAAiD;IACjD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,QAAQ,CAAC;CACpC;AAED,kFAAkF;AAClF,eAAO,MAAM,eAAe,QAAQ,CAAC;AACrC,yCAAyC;AACzC,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAC5C,4CAA4C;AAC5C,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAWvC;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,KAAG,gBAA0C,CAAC;AAEzF;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGnD;AA2BD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAuBhF"}

package/dist/types/common/circuit-breaker.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A minimal in-process circuit breaker for outbound calls.
+ *
+ * Layer: plumbing. States: `closed` (calls flow) → `open` after `failureThreshold` consecutive failures
+ * (calls are refused without touching the network) → `half-open` once `resetAfterMs` has passed, when exactly
+ * one trial call is let through: success closes the circuit, failure re-opens it for another `resetAfterMs`.
+ * State is per instance (per process), so each client owns its breaker; nothing is shared between targets.
+ */
+/** Breaker state. */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+/** Breaker settings. */
+export interface CircuitBreakerOptions {
+    /** Consecutive failures that open the circuit (default 5). */
+    failureThreshold?: number;
+    /** How long the circuit stays open before one trial call is allowed (default 30 000 ms). */
+    resetAfterMs?: number;
+    /** Clock, for tests (default `Date.now`). */
+    now?: () => number;
+}
+/**
+ * Counts consecutive failures and refuses calls while open.
+ *
+ * @example
+ * const breaker = new CircuitBreaker({ failureThreshold: 5, resetAfterMs: 30_000 });
+ * if (!breaker.tryAcquire()) throw new TargetUnavailableError();
+ * try { const r = await call(); breaker.onSuccess(); return r; } catch (e) { breaker.onFailure(); throw e; }
+ */
+export declare class CircuitBreaker {
+    private readonly failureThreshold;
+    private readonly resetAfterMs;
+    private readonly now;
+    private failures;
+    private openedAt;
+    private current;
+    private trialInFlight;
+    /** @param options Threshold, reset time and clock. @throws Error when a setting is not a positive number. */
+    constructor(options?: CircuitBreakerOptions);
+    /** The current state (an open circuit whose reset time has passed reports `half-open`). */
+    get state(): CircuitState;
+    /**
+     * Asks to make a call. While half-open only the first caller gets the trial; the rest are refused until it settles.
+     *
+     * @returns True when the call may go ahead; the caller must then report {@link onSuccess} or {@link onFailure}.
+     */
+    tryAcquire(): boolean;
+    /** Records a successful call: closes the circuit and clears the failure count. */
+    onSuccess(): void;
+    /** Records a failed call: a failed trial re-opens at once; otherwise opens after `failureThreshold` in a row. */
+    onFailure(): void;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/types/common/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../../src/common/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qBAAqB;AACrB,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,wBAAwB;AACxB,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,aAAa,CAAS;IAE9B,6GAA6G;gBACjG,OAAO,GAAE,qBAA0B;IAO/C,2FAA2F;IAC3F,IAAI,KAAK,IAAI,YAAY,CAGxB;IAED;;;;OAIG;IACH,UAAU,IAAI,OAAO;IASrB,kFAAkF;IAClF,SAAS,IAAI,IAAI;IAMjB,iHAAiH;IACjH,SAAS,IAAI,IAAI;CAQlB"}

package/dist/types/common/index.d.ts

@@ -7,6 +7,10 @@ export * from './jwt.js';
 export * from './text.js';
 export * from './async.js';
 export * from './phone.js';
+export * from './money.js';
 export * from './time.js';
 export * from './audit.js';
+export * from './circuit-breaker.js';
+export * from './internal-service-auth.js';
+export * from './internal-client.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/common/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC"}

package/dist/types/common/internal-client.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Typed HTTP client base for service-to-service (`internal`) calls.
+ *
+ * Layer: plumbing for a service's `src/clients/{target}.client.ts`. Key rules:
+ * - Sends the caller's own credential (`x-internal-service-name` + `x-internal-service-secret`) on every call,
+ *   the current correlation id (INT-12) and, when given, the end user's signed identity headers unchanged.
+ * - Callers can tell "service down" from "service said no": network errors, timeouts, 5xx, unreadable bodies
+ *   and an open circuit all throw the target's `{Target}UnavailableError` (503); a 4xx throws an `AppError`
+ *   carrying the remote status, code, message and field errors.
+ * - Only GET is retried (default 2 retries, 100 ms then 400 ms back-off), and only for network errors,
+ *   timeouts and 502/503/504. Mutating calls are never retried here; they accept an idempotency key instead.
+ * - Each client owns one {@link CircuitBreaker}; a call that ends unavailable counts as a failure, any HTTP
+ *   answer below 500 counts as a success.
+ * - Secrets and header values are never logged; failure logs carry target, method, path and reason only.
+ */
+import type { ZodType } from 'zod';
+import { type CircuitBreakerOptions, type CircuitState } from './circuit-breaker.js';
+import { ServiceUnavailableError } from './errors.js';
+import { type InternalCallerCredential } from './internal-service-auth.js';
+import type { Logger } from '../types/index.js';
+/** An unavailable-error class bound to one target service. Instances are 503 `ServiceUnavailableError`s. */
+export type UnavailableErrorClass = new (message?: string, options?: {
+    cause?: unknown;
+}) => ServiceUnavailableError & {
+    readonly target: string;
+};
+/**
+ * Returns the `{Target}UnavailableError` class for a target service (the same class on every call, so
+ * `instanceof` works anywhere in the process).
+ *
+ * @param target The target service name, e.g. `records-service`.
+ * @returns A class named e.g. `RecordsServiceUnavailableError`, extending `ServiceUnavailableError` (503).
+ * @example
+ * const RecordsUnavailable = makeUnavailableError('records-service');
+ * try { await records.get('/records/1'); } catch (e) { if (e instanceof RecordsUnavailable) useCachedCopy(); }
+ */
+export declare function makeUnavailableError(target: string): UnavailableErrorClass;
+/** Settings for {@link createInternalClient}. */
+export interface InternalClientOptions {
+    /** Target service name (compose name), e.g. `records-service`; names the unavailable error. */
+    target: string;
+    /** Target base URL on the private network, e.g. `http://records-service:4000/internal`. */
+    baseUrl: string;
+    /** This service's name and secret; defaults to env `INTERNAL_SERVICE_NAME` / `INTERNAL_SERVICE_CREDENTIAL`. */
+    caller?: InternalCallerCredential;
+    /** Per-attempt timeout (default 3000 ms). */
+    timeoutMs?: number;
+    /** Extra attempts for GET (default 2). */
+    retries?: number;
+    /** Delay before retry n (1-based) is `backoffMs[n-1]`, the last value repeating (default `[100, 400]`). */
+    backoffMs?: readonly number[];
+    /** Breaker settings (default `{ failureThreshold: 5, resetAfterMs: 30000 }`). */
+    breaker?: CircuitBreakerOptions;
+    /** Receives a warning per unavailable call (target, method, path, reason). */
+    logger?: Logger;
+    /** Fetch implementation, for tests (default global `fetch`). */
+    fetch?: typeof fetch;
+}
+/** Options for one call. */
+export interface InternalRequestOptions<T = unknown> {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /** Overrides the correlation id taken from the request context. */
+    correlationId?: string;
+    /**
+     * The end user's gateway identity headers, forwarded unchanged. Gateway signatures are bound to method and
+     * path, so a service acting for a user re-signs them for this exact call with `signedIdentityHeaders`.
+     */
+    identityHeaders?: Record<string, string>;
+    /** Sent as `idempotency-key` so the target can dedupe a mutating call the caller repeats. */
+    idempotencyKey?: string;
+    /** Overrides the client's per-attempt timeout. */
+    timeoutMs?: number;
+    /** Validates the unwrapped `data`; a mismatch throws the unavailable error (the contract is broken). */
+    schema?: ZodType<T>;
+}
+/** A client bound to one target service. */
+export interface InternalClient {
+    readonly target: string;
+    /** This target's unavailable error class, for `instanceof` checks. */
+    readonly UnavailableError: UnavailableErrorClass;
+    /** Current breaker state, for health and metrics. */
+    readonly circuitState: CircuitState;
+    /**
+     * Sends one call to the target. `get` is retried on transient failures; `post`/`put`/`patch`/`delete` never are.
+     *
+     * @param path Path under `baseUrl`, e.g. `/records/01J…`.
+     * @param options Query, body, correlation/identity headers, idempotency key, timeout and response schema.
+     * @returns The unwrapped `data` of the target's success envelope (validated when `schema` is given).
+     * @throws `{Target}UnavailableError` (503) when the target is down, slow, answers 5xx, sends an unreadable or
+     *   schema-mismatched body, or the circuit is open; `AppError` with the remote status/code for a 4xx.
+     * @example const record = await records.get('/records/01J…', { schema: recordSchema });
+     */
+    get<T>(path: string, options?: InternalRequestOptions<T>): Promise<T>;
+    /** Same as {@link InternalClient.get}, never retried; pass `idempotencyKey` so the target can dedupe a repeat. */
+    post<T>(path: string, options?: InternalRequestOptions<T>): Promise<T>;
+    /** Same as {@link InternalClient.post}. */
+    put<T>(path: string, options?: InternalRequestOptions<T>): Promise<T>;
+    /** Same as {@link InternalClient.post}. */
+    patch<T>(path: string, options?: InternalRequestOptions<T>): Promise<T>;
+    /** Same as {@link InternalClient.post}. */
+    delete<T>(path: string, options?: InternalRequestOptions<T>): Promise<T>;
+}
+/**
+ * Creates a client for one target service.
+ *
+ * @param options Target, base URL, caller credential, timeout, retry, breaker and logger settings.
+ * @returns An {@link InternalClient}.
+ * @throws ConfigError when the caller name or credential is missing.
+ * @example
+ * // src/clients/records.client.ts
+ * const http = createInternalClient({ target: 'records-service', baseUrl: config.RECORDS_INTERNAL_URL, logger });
+ * export const getRecord = (id: string) => http.get(`/records/${id}`, { schema: recordSchema });
+ */
+export declare function createInternalClient(options: InternalClientOptions): InternalClient;
+//# sourceMappingURL=internal-client.d.ts.map

package/dist/types/common/internal-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-client.d.ts","sourceRoot":"","sources":["../../../src/common/internal-client.ts"],"names":[],"mappings":"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"}

package/dist/types/common/internal-constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Leaf constants for internal-service auth, shared by `common/internal-service-auth` and the `config` env blocks
+ * (kept dependency-free so neither module imports the other).
+ */
+/** Shortest internal credential accepted in staging and production. */
+export declare const MIN_INTERNAL_CREDENTIAL_LENGTH = 32;
+/** Service names are compose-style: lower-case letters, digits and hyphens, starting with a letter. */
+export declare const SERVICE_NAME_PATTERN: RegExp;
+//# sourceMappingURL=internal-constants.d.ts.map

package/dist/types/common/internal-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-constants.d.ts","sourceRoot":"","sources":["../../../src/common/internal-constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,uEAAuE;AACvE,eAAO,MAAM,8BAA8B,KAAK,CAAC;AACjD,uGAAuG;AACvG,eAAO,MAAM,oBAAoB,QAA2B,CAAC"}