@grow-codes/aws-secrets-manager 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,213 @@
1
+ /** Result of `client.health()` (SPEC §2.4). */
2
+ interface HealthStatus {
3
+ /** Whether the service answered and reports itself usable. */
4
+ healthy: boolean;
5
+ /** `"ok" | "degraded" | "unhealthy" | "unreachable"` or the vendor's word. */
6
+ status: string;
7
+ /** Extra vendor details (string values). */
8
+ details: Record<string, string>;
9
+ }
10
+ /** True when a vendor status word means healthy. */
11
+ declare function isHealthyWord(status: string): boolean;
12
+ /** Builds a {@link HealthStatus}; `healthy` defaults to {@link isHealthyWord}(status). */
13
+ declare function healthStatus(status: string, details?: Record<string, unknown>, healthy?: boolean): HealthStatus;
14
+ /**
15
+ * Runs a health probe and converts failures into a {@link HealthStatus} (SPEC §2.4): network
16
+ * errors and timeouts → `unreachable`; HTTP errors → `unhealthy` (with the status code in
17
+ * `details.httpStatus`). Only `CANCELLED` and `CONFIG` errors are rethrown.
18
+ */
19
+ declare function probeHealth(probe: () => Promise<HealthStatus>): Promise<HealthStatus>;
20
+
21
+ declare const INSPECT: unique symbol;
22
+ /**
23
+ * A secret value. Every string form (`toString`, `JSON.stringify`, `util.inspect`) prints
24
+ * `SecretValue([REDACTED])`; use {@link reveal}, {@link revealBytes} or {@link json} to read it.
25
+ */
26
+ declare class SecretValue {
27
+ #private;
28
+ /** Opaque version string (KV `"3"`, AWS VersionId, …) when the service has versions. */
29
+ readonly version?: string;
30
+ constructor(value: string | Uint8Array, version?: string);
31
+ /** Encodes a string, bytes or a JSON-serialisable object (objects are JSON-encoded). */
32
+ static from(value: string | Uint8Array | object, version?: string): SecretValue;
33
+ /** UTF-8 text. Throws {@link ValidationError} when the value is not valid UTF-8. */
34
+ reveal(): string;
35
+ /** A copy of the raw bytes. */
36
+ revealBytes(): Uint8Array;
37
+ /** Parses the value as JSON. Throws {@link ValidationError} when it is not JSON. */
38
+ json<T = unknown>(): T;
39
+ /** Hex SHA-256 of the bytes (used to detect changes when there is no version). */
40
+ sha256(): string;
41
+ /** Byte length. */
42
+ get byteLength(): number;
43
+ toString(): string;
44
+ toJSON(): string;
45
+ [INSPECT](): string;
46
+ }
47
+ /** Encodes a `set()` input: strings as UTF-8, bytes as is, objects as JSON. */
48
+ declare function encodeSecretInput(value: string | Uint8Array | object): Uint8Array;
49
+
50
+ /** Metadata of one secret (SPEC §3). */
51
+ interface SecretMetadata {
52
+ /** Full name, usable with `get()`. */
53
+ name: string;
54
+ /** Containing path when the service has paths. */
55
+ path?: string;
56
+ /** Current version. */
57
+ version?: string;
58
+ createdAt?: Date;
59
+ updatedAt?: Date;
60
+ tags: Record<string, string>;
61
+ /** Number of stored versions. */
62
+ versions?: number;
63
+ /** Vendor-specific extra fields. */
64
+ extra: Record<string, string>;
65
+ }
66
+ /** Cancellation option accepted by every I/O method. */
67
+ interface SignalOptions {
68
+ signal?: AbortSignal;
69
+ }
70
+ /** Options of `get` and the other reads. */
71
+ interface GetOptions extends SignalOptions {
72
+ /** Read this version instead of the current one. */
73
+ version?: string;
74
+ /** Mount/folder/path the name is relative to. */
75
+ path?: string;
76
+ }
77
+ /** Options of `set`. */
78
+ interface SetOptions extends SignalOptions {
79
+ path?: string;
80
+ /** Compare-and-set: the current version must equal this (0 = must not exist). */
81
+ cas?: number;
82
+ tags?: Record<string, string>;
83
+ description?: string;
84
+ }
85
+ /** Options of `delete`. */
86
+ interface DeleteOptions extends SignalOptions {
87
+ path?: string;
88
+ /** Delete only these versions. */
89
+ versions?: string[];
90
+ /** Destroy permanently instead of soft-deleting where the service distinguishes. */
91
+ permanent?: boolean;
92
+ }
93
+ /** Options of `loadEnv`. */
94
+ interface LoadEnvOptions extends SignalOptions {
95
+ /** Replace variables that already exist (default false). */
96
+ override?: boolean;
97
+ /** Prefix added to every variable name (path form only, default `""`). */
98
+ prefix?: string;
99
+ /** Target environment (default `process.env`). */
100
+ env?: Record<string, string | undefined>;
101
+ }
102
+ /** Options of `watch`. */
103
+ interface WatchOptions {
104
+ /** Called for read errors and `onChange` failures; polling continues. */
105
+ onError?: (error: unknown) => void;
106
+ /** Options passed to every read. */
107
+ get?: GetOptions;
108
+ }
109
+ /** Handle returned by `watch`. */
110
+ interface WatchHandle {
111
+ /** Stops polling. Idempotent. */
112
+ stop(): void;
113
+ /** Whether {@link stop} was called. */
114
+ readonly stopped: boolean;
115
+ /** Resolves once the initial value has been read (or the first read failed). */
116
+ readonly ready: Promise<void>;
117
+ }
118
+ /** Called when a watched secret changes; `newValue` is `null` after deletion. */
119
+ type WatchCallback = (newValue: SecretValue | null, oldValue: SecretValue | null) => void | Promise<void>;
120
+ /** Input accepted by `set`: text, bytes or a JSON-serialisable object. */
121
+ type SecretInput = string | Uint8Array | object;
122
+ /** The secrets interface every secrets service implements (SPEC §3). */
123
+ interface SecretsProvider {
124
+ /** The secret, or `null` when missing. */
125
+ get(name: string, options?: GetOptions): Promise<SecretValue | null>;
126
+ /** UTF-8 text, or `null` when missing. */
127
+ getString(name: string, options?: GetOptions): Promise<string | null>;
128
+ /** Parsed JSON, or `null` when missing (`ValidationError` when not JSON). */
129
+ getJson<T = unknown>(name: string, options?: GetOptions): Promise<T | null>;
130
+ /** Number, or `null` when missing (`ValidationError` when not a number). */
131
+ getNumber(name: string, options?: GetOptions): Promise<number | null>;
132
+ /** Boolean (`true/false/1/0/yes/no/on/off`), or `null` when missing. */
133
+ getBool(name: string, options?: GetOptions): Promise<boolean | null>;
134
+ /** The secret; `NotFoundError` when missing. */
135
+ require(name: string, options?: GetOptions): Promise<SecretValue>;
136
+ /** Whether the secret exists. */
137
+ exists(name: string, options?: GetOptions): Promise<boolean>;
138
+ /** Present secrets in request order (missing names omitted). */
139
+ getMany(names: readonly string[], options?: GetOptions): Promise<Map<string, SecretValue>>;
140
+ /** Every secret directly under `path` (non-recursive), keyed by full name. */
141
+ getAll(path?: string, options?: SignalOptions): Promise<Map<string, SecretValue>>;
142
+ /** Metadata of the secrets directly under a prefix or path, sorted by name. */
143
+ list(prefixOrPath?: string, options?: SignalOptions): Promise<SecretMetadata[]>;
144
+ /** Writes a secret; returns the new version (`""` when the service has no versions). */
145
+ set(name: string, value: SecretInput, options?: SetOptions): Promise<string>;
146
+ /** Deletes a secret; `NotFoundError` when missing. */
147
+ delete(name: string, options?: DeleteOptions): Promise<void>;
148
+ /** Metadata, or `null` when missing. */
149
+ metadata(name: string, options?: GetOptions): Promise<SecretMetadata | null>;
150
+ /**
151
+ * Sets environment variables from secrets: a path (one variable per secret directly under it)
152
+ * or a mapping `{ ENV_NAME: "secret/name" }`. Returns `{ envName: secretName }` for the
153
+ * variables that were set (never values).
154
+ */
155
+ loadEnv(source: string | Readonly<Record<string, string>>, options?: LoadEnvOptions): Promise<Record<string, string>>;
156
+ /** Polls a secret and calls `onChange` when its version (or SHA-256) changes. */
157
+ watch(name: string, intervalMs: number, onChange: WatchCallback, options?: WatchOptions): WatchHandle;
158
+ }
159
+
160
+ /** Concurrency used by {@link BaseSecretsProvider.getMany}. */
161
+ declare const GET_MANY_CONCURRENCY = 8;
162
+ /**
163
+ * Implements the whole {@link SecretsProvider} interface from five primitives a service
164
+ * implements on top of its API (SPEC §3).
165
+ */
166
+ declare abstract class BaseSecretsProvider implements SecretsProvider {
167
+ #private;
168
+ /** Reads a secret; `null` when missing. */
169
+ protected abstract fetchSecret(name: string, options: GetOptions): Promise<SecretValue | null>;
170
+ /** Lists the secrets directly under a prefix or path (any order). */
171
+ protected abstract listSecrets(prefixOrPath: string | undefined, options: SignalOptions): Promise<SecretMetadata[]>;
172
+ /** Writes a secret; returns the new version or `""`. */
173
+ protected abstract putSecret(name: string, value: Uint8Array, options: SetOptions): Promise<string>;
174
+ /** Deletes a secret; must throw {@link NotFoundError} when missing. */
175
+ protected abstract removeSecret(name: string, options: DeleteOptions): Promise<void>;
176
+ /** Reads metadata; `null` when missing. */
177
+ protected abstract fetchMetadata(name: string, options: GetOptions): Promise<SecretMetadata | null>;
178
+ get(name: string, options?: GetOptions): Promise<SecretValue | null>;
179
+ getString(name: string, options?: GetOptions): Promise<string | null>;
180
+ getJson<T = unknown>(name: string, options?: GetOptions): Promise<T | null>;
181
+ getNumber(name: string, options?: GetOptions): Promise<number | null>;
182
+ getBool(name: string, options?: GetOptions): Promise<boolean | null>;
183
+ require(name: string, options?: GetOptions): Promise<SecretValue>;
184
+ exists(name: string, options?: GetOptions): Promise<boolean>;
185
+ getMany(names: readonly string[], options?: GetOptions): Promise<Map<string, SecretValue>>;
186
+ getAll(path?: string, options?: SignalOptions): Promise<Map<string, SecretValue>>;
187
+ list(prefixOrPath?: string, options?: SignalOptions): Promise<SecretMetadata[]>;
188
+ set(name: string, value: SecretInput, options?: SetOptions): Promise<string>;
189
+ delete(name: string, options?: DeleteOptions): Promise<void>;
190
+ metadata(name: string, options?: GetOptions): Promise<SecretMetadata | null>;
191
+ loadEnv(source: string | Readonly<Record<string, string>>, options?: LoadEnvOptions): Promise<Record<string, string>>;
192
+ watch(name: string, intervalMs: number, onChange: WatchCallback, options?: WatchOptions): WatchHandle;
193
+ /** Number of active watchers. */
194
+ get activeWatchers(): number;
195
+ /** Stops every watcher started by this provider. Idempotent. */
196
+ stopWatchers(): void;
197
+ /** Whether {@link close} was called. */
198
+ get closed(): boolean;
199
+ /**
200
+ * Throws `CancelledError` (`"<operation>: client is closed"`, not retryable) once {@link close}
201
+ * was called (SPEC §2.4). The public operations call it before any I/O; service operations
202
+ * can call it too.
203
+ */
204
+ protected ensureOpen(operation: string): void;
205
+ /**
206
+ * Stops all watchers (the owning client calls this from `close()`); later calls fail with
207
+ * `CANCELLED`. Idempotent. Subclasses overriding it must call `super.close()`.
208
+ */
209
+ close(): Promise<void>;
210
+ }
211
+
212
+ export { BaseSecretsProvider as B, SecretValue as a, GET_MANY_CONCURRENCY as h, encodeSecretInput as i, healthStatus as j, isHealthyWord as k, probeHealth as p };
213
+ export type { DeleteOptions as D, GetOptions as G, HealthStatus as H, LoadEnvOptions as L, SecretsProvider as S, WatchCallback as W, SignalOptions as b, SecretMetadata as c, SetOptions as d, WatchOptions as e, WatchHandle as f, SecretInput as g };