hanzio 2.0.0 → 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kristoffer Hansen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1156,9 +1156,8 @@ bun run build
 
 ## Releasing
 
-Releases are cut by [Release Please](https://github.com/googleapis/release-please)
-from squash-merged PR titles written as conventional commits. `feat:` bumps the
-minor version, `fix:` the patch, `feat!:` or a `BREAKING CHANGE:` footer the
-major. `chore:`, `ci:`, `docs:`, `refactor:` and `test:` do not release. Each
-merge to main updates a release PR; merging that PR tags the version and
-publishes to npm. Nobody runs `npm publish` locally.
+Squash PRs with conventional titles (`fix:`, `feat:`, or `feat!:`). Release Please keeps the version and changelog in a release PR; merge that PR to publish with release notes and npm provenance. See [release and recovery instructions](docs/releasing.md).
+
+## License
+
+[MIT](LICENSE).

package/dist/api-wrapper/endpoint.d.ts

@@ -1,10 +1,11 @@
 import type { z } from 'zod';
-import type { ApiEndpoint } from './types';
+import type { ApiEndpoint, CheckResponseContext } from './types';
 /**
  * Defines an endpoint with full inference, as an alternative to
  * `satisfies ApiEndpoint`: `resFormatter` must return what `resSchema`
- * accepts, and a literal `path` types its `:params` (making `reqParams`
- * required when there's no `reqParamsSchema`).
+ * accepts, `checkResponse` receives the parsed `resSchema` output, and a
+ * literal `path` types its `:params` (making `reqParams` required when
+ * there's no `reqParamsSchema`).
  *
  * @example
  * export const usersGet = defineEndpoint({
@@ -13,6 +14,8 @@ import type { ApiEndpoint } from './types';
  *   resSchema: User
  * })
  */
-export declare function defineEndpoint<const TEndpoint extends ApiEndpoint>(endpoint: TEndpoint & {
-    resFormatter?: (data: unknown, headers: Record<string, string>) => z.input<TEndpoint['resSchema']>;
+export declare function defineEndpoint<const TEndpoint extends Omit<ApiEndpoint, 'checkResponse'>, TRes extends z.ZodType = TEndpoint['resSchema']>(endpoint: TEndpoint & {
+    resSchema: TRes;
+    resFormatter?: (data: unknown, headers: Record<string, string>) => z.input<TRes>;
+    checkResponse?: ((data: z.output<TRes>, context: CheckResponseContext) => void | Promise<void>) | false;
 }): TEndpoint;

package/dist/api-wrapper/transport.d.ts

@@ -49,6 +49,7 @@ export declare function makeRequestWithRetry<TValidated>(args: MakeRequestArgs<T
 export declare function validateAndTransformResponse<T extends z.ZodType>(endpoint: ApiEndpoint<z.ZodType | undefined, z.ZodType | undefined, z.ZodType | undefined, z.ZodType | undefined, T>, response: Response, ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext): Promise<{
     data: z.infer<T>;
     responseSizeBytes: number;
+    headers: Record<string, string>;
 }>;
 export declare function defaultShouldRetry(ctx: RetryContext): boolean;
 export {};

package/dist/api-wrapper/types.d.ts

@@ -17,6 +17,11 @@ export interface ApiEndpoint<TReqBody extends z.ZodType | undefined = z.ZodType
     resFormatter?: (data: unknown, headers: Record<string, string>) => z.input<TResponse>;
     reqDefaultQueryParams?: QueryParams;
     doNotEncodeQueryParams?: boolean;
+    /**
+     * Replaces the client's `checkResponse` for this endpoint; `false` skips it.
+     * `defineEndpoint` types `data` as the parsed `resSchema` output.
+     */
+    checkResponse?: ((data: any, context: CheckResponseContext) => void | Promise<void>) | false;
 }
 export interface ApiWrapperResponse<T> {
     data: T;
@@ -25,6 +30,8 @@ export interface ApiWrapperResponse<T> {
     responseTimeMs: number;
     httpStatus: number;
     retryCount: number;
+    /** Response headers of the final attempt, keyed by lowercase name. */
+    headers: Record<string, string>;
 }
 export type RetryContext = {
     error?: unknown;

package/dist/{index-wjyb9bsd.js → index-hyt6c56h.js}

@@ -1,6 +1,6 @@
 import {
   SecretLoadError2
-} from "./index-srt06xd2.js";
+} from "./index-ktynw3vs.js";
 
 // src/secrets/environment.ts
 function getProcessEnvironment() {
@@ -92,9 +92,10 @@ function readOverrides(keys, env) {
     return value ? [[key, value]] : [];
   }));
 }
-async function defineSecretSet2(keys, options, environmentVariables) {
+function createSecretSet2(keys, options, environmentVariables) {
   const keySet = [...new Set(keys)];
-  const environment = resolveSecretEnvironment(options.environment, environmentVariables);
+  let environment;
+  let initialized = false;
   const logger = options.logger === false ? undefined : options.logger ?? defaultLogger;
   let cached;
   let parsed;
@@ -105,7 +106,7 @@ async function defineSecretSet2(keys, options, environmentVariables) {
       logger?.[level](message, attributes);
     } catch {}
   };
-  const loadSnapshot = async (request, signal) => {
+  const loadSnapshot = async (request, signal, environment) => {
     const local = readOverrides(keySet, environmentVariables);
     const missing = keySet.filter((key) => !Object.hasOwn(local, key));
     let loaderSource = options.loader.source ?? "custom loader";
@@ -171,6 +172,7 @@ async function defineSecretSet2(keys, options, environmentVariables) {
     cached = next;
     parsed = nextParsed;
     sources = nextSources;
+    initialized = true;
   };
   const load = (request = {}) => {
     if (inFlight) {
@@ -179,10 +181,12 @@ async function defineSecretSet2(keys, options, environmentVariables) {
     inFlight = (async () => {
       const start = Date.now();
       try {
+        environment ??= resolveSecretEnvironment(options.environment, environmentVariables);
+        const resolvedEnvironment = environment;
         await withSecretDeadline({
           timeoutMs: request.timeoutMs ?? options.timeoutMs,
           signal: request.signal ?? options.signal
-        }, (signal) => loadSnapshot(request, signal));
+        }, (signal) => loadSnapshot(request, signal, resolvedEnvironment));
         const sourceCounts = new Map;
         for (const key of keySet) {
           const source = sources[key];
@@ -190,7 +194,7 @@ async function defineSecretSet2(keys, options, environmentVariables) {
         }
         const counts = Object.fromEntries(sourceCounts);
         log("info", "Loaded secrets", {
-          environment,
+          environment: resolvedEnvironment,
           count: keySet.length,
           durationMs: Date.now() - start,
           source: Object.keys(counts).join(" + ") || "none",
@@ -199,7 +203,7 @@ async function defineSecretSet2(keys, options, environmentVariables) {
       } catch (error) {
         const safe = error instanceof SecretLoadError2 ? error : new SecretLoadError2("LOADER", "Secret loading failed.");
         log("error", "Secret loading failed", {
-          environment,
+          environment: environment ?? "unresolved",
           count: keySet.length,
           durationMs: Date.now() - start,
           code: safe.code
@@ -211,24 +215,47 @@ async function defineSecretSet2(keys, options, environmentVariables) {
     });
     return inFlight;
   };
+  const assertLoaded = () => {
+    if (!initialized) {
+      throw new SecretLoadError2("CONFIGURATION", "Secret set has not been loaded. Await load() before reading values.");
+    }
+  };
   const secretSet = {
     secret(key) {
+      assertLoaded();
       if (!Object.hasOwn(cached, key)) {
         throw new SecretLoadError2("MISSING_SECRETS", `Secret ${key} not found`);
       }
       return cached[key];
     },
-    secrets: () => ({ ...cached }),
-    parsed: () => structuredClone(parsed),
-    sources: () => ({ ...sources }),
+    secrets() {
+      assertLoaded();
+      return { ...cached };
+    },
+    parsed() {
+      assertLoaded();
+      return structuredClone(parsed);
+    },
+    sources() {
+      assertLoaded();
+      return { ...sources };
+    },
+    async load(request) {
+      if (!initialized) {
+        await load(request);
+      }
+      return secretSet;
+    },
     async reload(request) {
       await load(request);
       return secretSet;
     }
   };
-  await load();
   return secretSet;
 }
+async function defineSecretSet2(keys, options, environmentVariables) {
+  return createSecretSet2(keys, options, environmentVariables).load();
+}
 
 // src/secrets/worker-loader.ts
 function cloudflareWorkerEnvLoader2(workerEnv) {
@@ -260,4 +287,4 @@ function workerBindingToString(value) {
   return String(value);
 }
 
-export { withSecretDeadline, getProcessEnvironment, resolveSecretEnvironment, defineSecretSet2, cloudflareWorkerEnvLoader2 };
+export { withSecretDeadline, getProcessEnvironment, resolveSecretEnvironment, createSecretSet2, defineSecretSet2, cloudflareWorkerEnvLoader2 };

package/dist/index-ktynw3vs.js

@@ -0,0 +1,37 @@
+// src/secrets/errors.ts
+class SecretLoadError2 extends Error {
+  code;
+  operation;
+  status;
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "SecretLoadError";
+    this.code = code;
+    this.operation = details.operation;
+    this.status = details.status;
+  }
+}
+
+// src/secrets/public-config.ts
+function readPublicConfig2(keys, values) {
+  const snapshot = Object.fromEntries(keys.map((key) => [
+    key,
+    Object.hasOwn(values, key) ? values[key] : undefined
+  ]));
+  const missing = keys.filter((key) => typeof snapshot[key] !== "string" || !snapshot[key]);
+  if (missing.length) {
+    throw new SecretLoadError2("MISSING_SECRETS", `Missing required public configuration: ${missing.join(", ")}`);
+  }
+  const configured = snapshot;
+  return {
+    secret(key) {
+      if (!Object.hasOwn(configured, key)) {
+        throw new SecretLoadError2("CONFIGURATION", `Public key ${key} is not configured.`);
+      }
+      return configured[key];
+    },
+    secrets: () => ({ ...configured })
+  };
+}
+
+export { SecretLoadError2, readPublicConfig2 };

package/dist/{index-181e6vfw.js → index-w882zry3.js}

@@ -1,6 +1,6 @@
 import {
   SecretLoadError2
-} from "./index-srt06xd2.js";
+} from "./index-ktynw3vs.js";
 
 // src/secrets/vite.ts
 function getViteDefine2(secretSet, options = {}) {

package/dist/{index-j1ybktbr.js → index-zbj9s3s3.js}

@@ -1006,7 +1006,7 @@ async function validateAndTransformResponse(endpoint, response, ctx) {
   }
   const transformedData = endpoint.resFormatter ? endpoint.resFormatter(responseData, responseHeaders) : responseData;
   const data = await validateResponse(endpoint.resSchema, transformedData, ctx);
-  return { data, responseSizeBytes };
+  return { data, responseSizeBytes, headers: responseHeaders };
 }
 function defaultShouldRetry2(ctx) {
   if (ctx.error)
@@ -1170,14 +1170,16 @@ function createApiClientImpl(apiConfig) {
         responseSizeMb: result.validatedData.responseSizeBytes / (1024 * 1024),
         responseTimeMs: elapsed(),
         httpStatus: result.httpStatus,
-        retryCount: result.retryCount
+        retryCount: result.retryCount,
+        headers: result.validatedData.headers
       };
     };
     const runCheckResponse = async (data, httpStatus, attempt) => {
-      if (!apiConfig.checkResponse)
+      const checkResponse = endpoint.checkResponse === undefined ? apiConfig.checkResponse : endpoint.checkResponse;
+      if (!checkResponse)
         return;
       try {
-        await apiConfig.checkResponse(data, {
+        await checkResponse(data, {
           endpoint: endpointName,
           method: endpoint.method,
           url: fullUrl,

package/dist/secrets/core.d.ts

@@ -44,4 +44,11 @@ export type SecretSet<K extends string, Parsed = Record<K, string>> = {
     sources: () => Record<K, string>;
     reload: (options?: SecretRequestOptions) => Promise<SecretSet<K, Parsed>>;
 };
+/** A declaration that must be loaded explicitly before its values can be read. */
+export type LazySecretSet<K extends string, Parsed = Record<K, string>> = SecretSet<K, Parsed> & {
+    /** Initialize once. Concurrent calls share a load; use reload to refresh. */
+    load: (options?: SecretRequestOptions) => Promise<LazySecretSet<K, Parsed>>;
+};
+export declare function createSecretSet<const Keys extends readonly string[], Parsed = Record<Keys[number], string>>(keys: Keys, options: CustomLoaderDefineSecretSetOptions<Keys[number], Parsed>, environmentVariables?: EnvironmentVariables): LazySecretSet<Keys[number], Parsed>;
+/** Compatibility API: declares and loads a complete snapshot before returning. */
 export declare function defineSecretSet<const Keys extends readonly string[], Parsed = Record<Keys[number], string>>(keys: Keys, options: CustomLoaderDefineSecretSetOptions<Keys[number], Parsed>, environmentVariables?: EnvironmentVariables): Promise<SecretSet<Keys[number], Parsed>>;

package/dist/secrets/index.d.ts

@@ -1,4 +1,4 @@
-import { type CommonSecretSetOptions, type CustomLoaderDefineSecretSetOptions, type SecretSet } from './core';
+import { type LazySecretSet, type CommonSecretSetOptions, type CustomLoaderDefineSecretSetOptions, type SecretSet } from './core';
 import { type SecretEnvironment } from './environment';
 import { type InfisicalAuthMode } from './infisical';
 import { type InfisicalProjectOptions } from './infisical-config';
@@ -15,4 +15,6 @@ export type InfisicalDefineSecretSetOptions<K extends string = string, Parsed =
 };
 export type DefineSecretSetOptions<K extends string, Parsed = Record<K, string>> = InfisicalDefineSecretSetOptions<K, Parsed> | CustomLoaderDefineSecretSetOptions<K, Parsed>;
 export declare function getSecretEnvironment(): SecretEnvironment;
+export declare function createSecretSet<const Keys extends readonly string[], Parsed = Record<Keys[number], string>>(keys: Keys, options: DefineSecretSetOptions<Keys[number], Parsed>): LazySecretSet<Keys[number], Parsed>;
+/** Compatibility API: load immediately and fail before application startup. */
 export declare function defineSecretSet<const Keys extends readonly string[], Parsed = Record<Keys[number], string>>(keys: Keys, options: DefineSecretSetOptions<Keys[number], Parsed>): Promise<SecretSet<Keys[number], Parsed>>;

package/dist/secrets/public-config.d.ts

@@ -0,0 +1,7 @@
+import type { SecretSet } from './core';
+/**
+ * Read only explicitly listed public values. No process globals, secret loader,
+ * environment writes, or async initialization; safe in frontend tooling.
+ * Validate application-specific formats with your schema after secrets().
+ */
+export declare function readPublicConfig<const Keys extends readonly string[]>(keys: Keys, values: Readonly<Record<string, string | undefined>>): Pick<SecretSet<Keys[number]>, 'secret' | 'secrets'>;

package/dist/secrets/vite.d.ts

@@ -11,3 +11,4 @@ export type ViteSecretSetOptions<K extends string> = {
 };
 export declare function getViteDefine<K extends string>(secretSet: Pick<SecretSet<K, unknown>, 'secrets'>, options?: ViteSecretSetOptions<K>): Record<string, string>;
 export declare function viteSecretSetPlugin<K extends string>(secretSet: Pick<SecretSet<K, unknown>, 'secrets'>, options?: ViteSecretSetOptions<K>): ViteSecretSetPlugin;
+export { readPublicConfig } from './public-config';

package/dist/secrets/worker.d.ts

@@ -1,3 +1,4 @@
 export * from './core';
 export { cloudflareWorkerEnvLoader } from './worker-loader';
 export type { SecretRequestOptions } from './deadline';
+export { readPublicConfig } from './public-config';

package/dist/src/api-wrapper/index.js

@@ -28,7 +28,7 @@ import {
   paginate2,
   otelMiddleware2,
   defineEndpoint2
-} from "../../index-j1ybktbr.js";
+} from "../../index-zbj9s3s3.js";
 export {
   ActionError2 as ActionError,
   ApiError2 as ApiError,

package/dist/src/secrets/index.js

@@ -1,21 +1,22 @@
 import {
   HttpResponseError2,
   createApiClient2
-} from "../../index-j1ybktbr.js";
+} from "../../index-zbj9s3s3.js";
 import {
   getViteDefine2,
   viteSecretSetPlugin2
-} from "../../index-181e6vfw.js";
+} from "../../index-w882zry3.js";
 import {
   withSecretDeadline,
   getProcessEnvironment,
   resolveSecretEnvironment,
-  defineSecretSet2,
+  createSecretSet2,
   cloudflareWorkerEnvLoader2
-} from "../../index-wjyb9bsd.js";
+} from "../../index-hyt6c56h.js";
 import {
-  SecretLoadError2
-} from "../../index-srt06xd2.js";
+  SecretLoadError2,
+  readPublicConfig2
+} from "../../index-ktynw3vs.js";
 
 // src/secrets/infisical.ts
 import { z as z2 } from "zod";
@@ -328,7 +329,7 @@ Object.assign(processEnvLoader, { source: "process.env" });
 function getSecretEnvironment() {
   return resolveSecretEnvironment(undefined, getProcessEnvironment());
 }
-async function defineSecretSet(keys, options) {
+function createSecretSet(keys, options) {
   let loader;
   if (!options.loader) {
     validateInfisicalOrganizationId(options.organizationId);
@@ -336,7 +337,7 @@ async function defineSecretSet(keys, options) {
   } else {
     loader = options.loader;
   }
-  return defineSecretSet2(keys, { ...options, loader }, getProcessEnvironment());
+  return createSecretSet2(keys, { ...options, loader }, getProcessEnvironment());
 }
 function createDefaultInfisicalLoader(options) {
   return (context) => loadInfisicalSecrets({
@@ -350,10 +351,14 @@ function createDefaultInfisicalLoader(options) {
     clientSecretEnvKey: options.clientSecretEnvKey ?? "INFISICAL_CLIENT_SECRET"
   });
 }
+async function defineSecretSet(keys, options) {
+  return createSecretSet(keys, options).load();
+}
 export {
   DEFAULT_INFISICAL_SITE_URL,
   SecretLoadError2 as SecretLoadError,
   cloudflareWorkerEnvLoader2 as cloudflareWorkerEnvLoader,
+  createSecretSet,
   defineSecretSet,
   fetchInfisicalSecrets,
   getSecretEnvironment,
@@ -361,5 +366,6 @@ export {
   infisicalLoader,
   loadInfisicalSecrets,
   processEnvLoader,
+  readPublicConfig2 as readPublicConfig,
   viteSecretSetPlugin2 as viteSecretSetPlugin
 };

package/dist/src/secrets/vite.js

@@ -1,8 +1,12 @@
 import {
   getViteDefine2,
   viteSecretSetPlugin2
-} from "../../index-181e6vfw.js";
+} from "../../index-w882zry3.js";
+import {
+  readPublicConfig2
+} from "../../index-ktynw3vs.js";
 export {
   getViteDefine2 as getViteDefine,
+  readPublicConfig2 as readPublicConfig,
   viteSecretSetPlugin2 as viteSecretSetPlugin
 };

package/dist/src/secrets/worker.js

@@ -1,12 +1,16 @@
 import {
+  createSecretSet2,
   defineSecretSet2,
   cloudflareWorkerEnvLoader2
-} from "../../index-wjyb9bsd.js";
+} from "../../index-hyt6c56h.js";
 import {
-  SecretLoadError2
-} from "../../index-srt06xd2.js";
+  SecretLoadError2,
+  readPublicConfig2
+} from "../../index-ktynw3vs.js";
 export {
   SecretLoadError2 as SecretLoadError,
   cloudflareWorkerEnvLoader2 as cloudflareWorkerEnvLoader,
-  defineSecretSet2 as defineSecretSet
+  createSecretSet2 as createSecretSet,
+  defineSecretSet2 as defineSecretSet,
+  readPublicConfig2 as readPublicConfig
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hanzio",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "A lightweight set of utility functions for TypeScript",
   "type": "module",
   "module": "./dist/src/index.js",
@@ -25,6 +25,7 @@
   },
   "files": [
     "src/**/*.ts",
+    "src/**/README.md",
     "dist",
     "!src/**/*.test.ts"
   ],
@@ -132,7 +133,8 @@
     "typecheck": "tsgo --noEmit",
     "prepare": "husky",
     "test:secrets:runtime": "bun run build && node scripts/verify-secrets.mjs",
-    "test:exports": "bun run build && node scripts/verify-exports.mjs"
+    "test:exports": "bun run build && node scripts/verify-exports.mjs",
+    "verify:package": "node scripts/verify-package.mjs"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",
@@ -152,5 +154,10 @@
     "zod": {
       "optional": true
     }
-  }
+  },
+  "homepage": "https://github.com/HansKristoffer/hanzio#readme",
+  "bugs": {
+    "url": "https://github.com/HansKristoffer/hanzio/issues"
+  },
+  "packageManager": "bun@1.4.2"
 }