@mi9-identity/token-client 1.0.0

package/dist/endpoints.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Derive the two Mi9 Identity endpoints this package talks to — `/oauth/token`
+ * for minting and `/credentials/me` for the GCP lazy claim and rotation pickup
+ * — from a single issuer URL. Deliberately local: the package has no dependency
+ * on `@mi9-identity/jwt-verifier`, so a consumer that only mints tokens never
+ * installs a JOSE stack to build two URLs. The JWKS URI is the verifier
+ * package's concern (`mi9IdentityJwksEndpoint`), not this one's.
+ *
+ * @param { string } issuerUrl Configured issuer URL (matches the JWT `iss` claim, e.g. `https://identity.mi9retail.com/api/v1`). Trailing slash tolerated.
+ * @returns { Readonly<{ tokenEndpoint: string; credentialEndpoint: string }> } Frozen record of `tokenEndpoint` and `credentialEndpoint`.
+ */
+export declare const mi9IdentityEndpoints: (issuerUrl: string) => Readonly<{
+    readonly tokenEndpoint: `${string}/oauth/token`;
+    readonly credentialEndpoint: `${string}/credentials/me`;
+}>;
+//# sourceMappingURL=endpoints.d.ts.map

package/dist/endpoints.js

@@ -0,0 +1,19 @@
+/**
+ * Derive the two Mi9 Identity endpoints this package talks to — `/oauth/token`
+ * for minting and `/credentials/me` for the GCP lazy claim and rotation pickup
+ * — from a single issuer URL. Deliberately local: the package has no dependency
+ * on `@mi9-identity/jwt-verifier`, so a consumer that only mints tokens never
+ * installs a JOSE stack to build two URLs. The JWKS URI is the verifier
+ * package's concern (`mi9IdentityJwksEndpoint`), not this one's.
+ *
+ * @param { string } issuerUrl Configured issuer URL (matches the JWT `iss` claim, e.g. `https://identity.mi9retail.com/api/v1`). Trailing slash tolerated.
+ * @returns { Readonly<{ tokenEndpoint: string; credentialEndpoint: string }> } Frozen record of `tokenEndpoint` and `credentialEndpoint`.
+ */
+export const mi9IdentityEndpoints = (issuerUrl) => {
+    const base = issuerUrl.replace(/\/+$/, '');
+    return Object.freeze({
+        tokenEndpoint: `${base}/oauth/token`,
+        credentialEndpoint: `${base}/credentials/me`,
+    });
+};
+//# sourceMappingURL=endpoints.js.map

package/dist/errors.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Retryable failure — the request failed in a way that suggests success on
+ * a later attempt (429, 503, timeout, transient network glitch). The token
+ * client retries internally with backoff before exposing this to callers.
+ */
+export declare class TransientError extends Error {
+    readonly name: string;
+}
+/**
+ * The credential secret was rejected (HTTP 401 from `/oauth/token` or
+ * `/credentials/me`). The client does NOT retry with the same secret. A GCP
+ * (Tier 1) client configured with an `idTokenProvider` re-claims once
+ * automatically before surfacing this; Tier 2/3 callers escalate to operators.
+ */
+export declare class RevocationError extends Error {
+    readonly name: string;
+}
+/**
+ * Credential not provisioned or not usable for the grant it was presented
+ * with — HTTP 404 from `/oauth/token` or from the `gcp_identity` lazy-claim at
+ * `/credentials/me` (the admin has not created the credential yet, or it was
+ * fully revoked), and HTTP 503 `degraded` from that same lazy-claim (a
+ * credential exists for the service account but is tagged with a non-`gcp`
+ * consumer type). The client cannot recover by retrying — an administrator has
+ * to create or correct the row first — but a later attempt succeeds once they
+ * have.
+ */
+export declare class ProvisioningError extends Error {
+    readonly name: string;
+}
+/**
+ * The Tier-1 GCP lazy-claim did not yield a usable credential — HTTP 401/403
+ * from the `gcp_identity` grant at `/credentials/me`, the injected
+ * `idTokenProvider` threw, or the claimed credential's `authorizedAudiences`
+ * does not cover the configured `audience`. Distinct from `RevocationError`
+ * (a rejected `clientSecret`) and `ProvisioningError` (no credential bound
+ * yet): in every case here the fix is to the ID-token provider, its audience,
+ * or the credential's grants — never a bare retry.
+ */
+export declare class LazyClaimError extends Error {
+    readonly name: string;
+}
+/**
+ * Server response did not match the expected schema. Re-exported so callers
+ * can narrow on it in a custom error handler, but it sits outside the
+ * Transient / Revocation / Provisioning taxonomy: a shape mismatch indicates
+ * an issuer-side bug, not a recoverable condition the client can retry.
+ */
+export declare class ResponseShapeError extends Error {
+    readonly name: string;
+}
+/**
+ * The client cannot work with the configuration it was given — options that do
+ * not describe a usable credential mode, or an `audience` the issuer refuses
+ * to mint for (HTTP 403 `invalid_target` from `/oauth/token`). Terminal and
+ * outside the Transient / Revocation / Provisioning taxonomy: no retry and no
+ * re-claim can clear it, because the fix is a code or credential change, not a
+ * later attempt.
+ */
+export declare class ConfigurationError extends Error {
+    readonly name: string;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,63 @@
+/**
+ * Retryable failure — the request failed in a way that suggests success on
+ * a later attempt (429, 503, timeout, transient network glitch). The token
+ * client retries internally with backoff before exposing this to callers.
+ */
+export class TransientError extends Error {
+    name = 'TransientError';
+}
+/**
+ * The credential secret was rejected (HTTP 401 from `/oauth/token` or
+ * `/credentials/me`). The client does NOT retry with the same secret. A GCP
+ * (Tier 1) client configured with an `idTokenProvider` re-claims once
+ * automatically before surfacing this; Tier 2/3 callers escalate to operators.
+ */
+export class RevocationError extends Error {
+    name = 'RevocationError';
+}
+/**
+ * Credential not provisioned or not usable for the grant it was presented
+ * with — HTTP 404 from `/oauth/token` or from the `gcp_identity` lazy-claim at
+ * `/credentials/me` (the admin has not created the credential yet, or it was
+ * fully revoked), and HTTP 503 `degraded` from that same lazy-claim (a
+ * credential exists for the service account but is tagged with a non-`gcp`
+ * consumer type). The client cannot recover by retrying — an administrator has
+ * to create or correct the row first — but a later attempt succeeds once they
+ * have.
+ */
+export class ProvisioningError extends Error {
+    name = 'ProvisioningError';
+}
+/**
+ * The Tier-1 GCP lazy-claim did not yield a usable credential — HTTP 401/403
+ * from the `gcp_identity` grant at `/credentials/me`, the injected
+ * `idTokenProvider` threw, or the claimed credential's `authorizedAudiences`
+ * does not cover the configured `audience`. Distinct from `RevocationError`
+ * (a rejected `clientSecret`) and `ProvisioningError` (no credential bound
+ * yet): in every case here the fix is to the ID-token provider, its audience,
+ * or the credential's grants — never a bare retry.
+ */
+export class LazyClaimError extends Error {
+    name = 'LazyClaimError';
+}
+/**
+ * Server response did not match the expected schema. Re-exported so callers
+ * can narrow on it in a custom error handler, but it sits outside the
+ * Transient / Revocation / Provisioning taxonomy: a shape mismatch indicates
+ * an issuer-side bug, not a recoverable condition the client can retry.
+ */
+export class ResponseShapeError extends Error {
+    name = 'ResponseShapeError';
+}
+/**
+ * The client cannot work with the configuration it was given — options that do
+ * not describe a usable credential mode, or an `audience` the issuer refuses
+ * to mint for (HTTP 403 `invalid_target` from `/oauth/token`). Terminal and
+ * outside the Transient / Revocation / Provisioning taxonomy: no retry and no
+ * re-claim can clear it, because the fix is a code or credential change, not a
+ * later attempt.
+ */
+export class ConfigurationError extends Error {
+    name = 'ConfigurationError';
+}
+//# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createGcpTokenClient, createTokenClient } from './client.js';
+export { claimGcpCredential } from './claim.js';
+export { mi9IdentityEndpoints } from './endpoints.js';
+export { ConfigurationError, LazyClaimError, ProvisioningError, ResponseShapeError, RevocationError, TransientError } from './errors.js';
+export { DEFAULT_BACKOFF } from './backoff.js';
+export type { AccessToken, BackoffPolicy, ClaimGcpCredentialOptions, CredentialClaim, GcpTokenClientOptions, Logger, TokenClient, TokenClientOptions } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createGcpTokenClient, createTokenClient } from './client.js';
+export { claimGcpCredential } from './claim.js';
+export { mi9IdentityEndpoints } from './endpoints.js';
+export { ConfigurationError, LazyClaimError, ProvisioningError, ResponseShapeError, RevocationError, TransientError } from './errors.js';
+export { DEFAULT_BACKOFF } from './backoff.js';
+//# sourceMappingURL=index.js.map

package/dist/oauth-error.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Best-effort extract of the `error` code from an issuer error envelope; falls
+ * back to `'unknown'` when the body is missing or malformed. Consumes the
+ * response body, so the caller must not read it again.
+ *
+ * @param { Response } response The non-2xx fetch response.
+ * @returns { Promise<string> } The `error` code value, or `'unknown'`.
+ */
+export declare const readOAuthErrorCode: (response: Response) => Promise<string>;
+/**
+ * Extract the `error` code plus the envelope's `errorDescription` when present.
+ * The issuer's machine-readable sub-codes are audit-only and never on the wire,
+ * so `errorDescription` is the only field that names the remedy — dropping it
+ * leaves a caller unable to tell `retailer_required` ("specify retailerCode")
+ * from an ordinary malformed body, since both are `invalid_request`.
+ *
+ * Consumes the response body, so the caller must not read it again.
+ *
+ * @param { Response } response The non-2xx fetch response.
+ * @returns { Promise<string> } `"<code>: <description>"`, or just the code when no description is present.
+ */
+export declare const readOAuthErrorDetail: (response: Response) => Promise<string>;
+//# sourceMappingURL=oauth-error.d.ts.map

package/dist/oauth-error.js

@@ -0,0 +1,42 @@
+import { oauthErrorSchema } from './schemas.js';
+import { isEmpty, isUndefined } from './type-guards.js';
+/**
+ * Best-effort parse of an issuer error envelope. Consumes the response body, so
+ * a caller must not read it again — and must not call two of the readers here
+ * on the same response.
+ *
+ * @param { Response } response The non-2xx fetch response.
+ * @returns { Promise<OauthError> } The parsed envelope, or an empty object when the body is missing or malformed.
+ */
+const readEnvelope = async (response) => {
+    const envelope = oauthErrorSchema.safeParse(await response.json().catch(() => ({})));
+    return envelope.success ? envelope.data : {};
+};
+/**
+ * Best-effort extract of the `error` code from an issuer error envelope; falls
+ * back to `'unknown'` when the body is missing or malformed. Consumes the
+ * response body, so the caller must not read it again.
+ *
+ * @param { Response } response The non-2xx fetch response.
+ * @returns { Promise<string> } The `error` code value, or `'unknown'`.
+ */
+export const readOAuthErrorCode = async (response) => (await readEnvelope(response)).error ?? 'unknown';
+/**
+ * Extract the `error` code plus the envelope's `errorDescription` when present.
+ * The issuer's machine-readable sub-codes are audit-only and never on the wire,
+ * so `errorDescription` is the only field that names the remedy — dropping it
+ * leaves a caller unable to tell `retailer_required` ("specify retailerCode")
+ * from an ordinary malformed body, since both are `invalid_request`.
+ *
+ * Consumes the response body, so the caller must not read it again.
+ *
+ * @param { Response } response The non-2xx fetch response.
+ * @returns { Promise<string> } `"<code>: <description>"`, or just the code when no description is present.
+ */
+export const readOAuthErrorDetail = async (response) => {
+    const envelope = await readEnvelope(response);
+    const code = envelope.error ?? 'unknown';
+    const description = envelope.errorDescription;
+    return isUndefined(description) || isEmpty(description) ? code : `${code}: ${description}`;
+};
+//# sourceMappingURL=oauth-error.js.map

package/dist/request-id.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolve the correlation id to send on one outbound request: invoke the
+ * caller's getter, pin the caller's fixed string, or mint a fresh UUID.
+ *
+ * @param { string | (() => string) | undefined } requestId The configured correlation-id source.
+ * @returns { string } The correlation id for this request.
+ */
+export declare const resolveRequestId: (requestId: string | (() => string) | undefined) => string;
+//# sourceMappingURL=request-id.d.ts.map

package/dist/request-id.js

@@ -0,0 +1,19 @@
+import { randomUUID } from 'node:crypto';
+import { isEmpty, isFunction, isString } from './type-guards.js';
+/**
+ * Resolve the correlation id to send on one outbound request: invoke the
+ * caller's getter, pin the caller's fixed string, or mint a fresh UUID.
+ *
+ * @param { string | (() => string) | undefined } requestId The configured correlation-id source.
+ * @returns { string } The correlation id for this request.
+ */
+export const resolveRequestId = (requestId) => {
+    if (isFunction(requestId)) {
+        return requestId();
+    }
+    if (isString(requestId) && !isEmpty(requestId)) {
+        return requestId;
+    }
+    return randomUUID();
+};
+//# sourceMappingURL=request-id.js.map

package/dist/schemas.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+/**
+ * `POST /oauth/token` success response. `credentialRotated` is the body
+ * flag described in design doc §3.3 / §5; the equivalent header is
+ * `X-Mi9-Credential-Rotated`.
+ */
+export declare const tokenResponseSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    tokenType: z.ZodLiteral<"Bearer">;
+    expiresIn: z.ZodNumber;
+    credentialRotated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+export type TokenResponse = z.infer<typeof tokenResponseSchema>;
+/**
+ * `POST /credentials/me` success response. `clientSecret` is the new active
+ * secret to swap in via `onSecretRotated`. Closed schema (`.strict()`) so a
+ * future caller that logs `parsed.data` for debugging cannot leak unknown
+ * fields the issuer adds later — and the secret-bearing payload is never
+ * silently widened.
+ */
+export declare const credentialMeResponseSchema: z.ZodObject<{
+    clientId: z.ZodString;
+    clientSecret: z.ZodString;
+    audience: z.ZodArray<z.ZodString>;
+    tokenUrl: z.ZodURL;
+}, z.core.$strict>;
+export type CredentialMeResponse = z.infer<typeof credentialMeResponseSchema>;
+/**
+ * `application/json` error envelope from `/oauth/token` and `/credentials/me`.
+ * Used to extract the `error` code for log lines without leaking the body to
+ * upstream callers. The error `code` stays snake_case (RFC 6749 §5.2 reserved),
+ * but the wrapping Mi9 fields are camelCase per ADR-12 — `errorDescription`,
+ * `requestId`.
+ */
+export declare const oauthErrorSchema: z.ZodObject<{
+    error: z.ZodOptional<z.ZodString>;
+    errorDescription: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    requestId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+export type OauthError = z.infer<typeof oauthErrorSchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+/**
+ * `POST /oauth/token` success response. `credentialRotated` is the body
+ * flag described in design doc §3.3 / §5; the equivalent header is
+ * `X-Mi9-Credential-Rotated`.
+ */
+export const tokenResponseSchema = z
+    .object({
+    accessToken: z.string().min(1),
+    tokenType: z.literal('Bearer'),
+    expiresIn: z.number().int().positive(),
+    credentialRotated: z.boolean().optional(),
+})
+    .passthrough();
+/**
+ * `POST /credentials/me` success response. `clientSecret` is the new active
+ * secret to swap in via `onSecretRotated`. Closed schema (`.strict()`) so a
+ * future caller that logs `parsed.data` for debugging cannot leak unknown
+ * fields the issuer adds later — and the secret-bearing payload is never
+ * silently widened.
+ */
+export const credentialMeResponseSchema = z
+    .object({
+    clientId: z.string().min(1),
+    clientSecret: z.string().min(1),
+    audience: z.array(z.string()),
+    tokenUrl: z.url(),
+})
+    .strict();
+/**
+ * `application/json` error envelope from `/oauth/token` and `/credentials/me`.
+ * Used to extract the `error` code for log lines without leaking the body to
+ * upstream callers. The error `code` stays snake_case (RFC 6749 §5.2 reserved),
+ * but the wrapping Mi9 fields are camelCase per ADR-12 — `errorDescription`,
+ * `requestId`.
+ */
+export const oauthErrorSchema = z
+    .object({
+    error: z.string(),
+    errorDescription: z.string().optional(),
+    requestId: z.string().optional(),
+})
+    .partial();
+//# sourceMappingURL=schemas.js.map

package/dist/token-client.constants.d.ts

@@ -0,0 +1,28 @@
+import type { Logger } from './types.js';
+/**
+ * Retry budget for transient (429 / 5xx / network) failures — the retry loop
+ * runs `MAX_RETRIES + 1` attempts in total before surfacing a `TransientError`.
+ */
+export declare const MAX_RETRIES = 5;
+/**
+ * Default outbound correlation-id header name. Casing matches the design
+ * doc's canonical form; HTTP transports normalize it on the wire.
+ */
+export declare const DEFAULT_REQUEST_ID_HEADER = "X-Request-ID";
+/**
+ * Default proactive-refresh lead time — a cached token is re-minted once it is
+ * within five minutes of expiry (T-5 min for a 1 h TTL).
+ */
+export declare const DEFAULT_REFRESH_LEAD_TIME_MS: number;
+/**
+ * Issuer error-envelope code accompanying a 503 when the credential bound to
+ * the caller's identity is not eligible for the grant it used. Operator
+ * misconfiguration, permanent until an administrator corrects the row — so it
+ * must never be treated as a retryable 5xx.
+ */
+export declare const OAUTH_ERROR_CODE_DEGRADED = "degraded";
+/**
+ * Structural no-op logger installed when the caller injects none.
+ */
+export declare const NOOP_LOGGER: Logger;
+//# sourceMappingURL=token-client.constants.d.ts.map

package/dist/token-client.constants.js

@@ -0,0 +1,33 @@
+/**
+ * Retry budget for transient (429 / 5xx / network) failures — the retry loop
+ * runs `MAX_RETRIES + 1` attempts in total before surfacing a `TransientError`.
+ */
+export const MAX_RETRIES = 5;
+/**
+ * Default outbound correlation-id header name. Casing matches the design
+ * doc's canonical form; HTTP transports normalize it on the wire.
+ */
+export const DEFAULT_REQUEST_ID_HEADER = 'X-Request-ID';
+/**
+ * Default proactive-refresh lead time — a cached token is re-minted once it is
+ * within five minutes of expiry (T-5 min for a 1 h TTL).
+ */
+export const DEFAULT_REFRESH_LEAD_TIME_MS = 5 * 60_000;
+/**
+ * Issuer error-envelope code accompanying a 503 when the credential bound to
+ * the caller's identity is not eligible for the grant it used. Operator
+ * misconfiguration, permanent until an administrator corrects the row — so it
+ * must never be treated as a retryable 5xx.
+ */
+export const OAUTH_ERROR_CODE_DEGRADED = 'degraded';
+/**
+ * Structural no-op logger installed when the caller injects none.
+ */
+export const NOOP_LOGGER = {
+    /* v8 ignore next -- debug is part of the structural Logger contract; the client never calls it but consumers may */
+    debug: () => undefined,
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+//# sourceMappingURL=token-client.constants.js.map

package/dist/type-guards.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Narrowing type guards, duplicated per package by design (see CLAUDE.md) —
+ * mirrored from the identity service's canonical `utils/type-guards.ts`, plus
+ * a package-local `isFunction` (the canonical set has no function guard).
+ */
+/**
+ * Strict null check.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is null } True iff `value === null`.
+ * @example
+ * isNull(null); // true
+ * isNull(undefined); // false
+ * isNull(0); // false
+ * isNull(''); // false
+ */
+export declare const isNull: (value: unknown) => value is null;
+/**
+ * Strict undefined check.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is undefined } True iff `value === undefined`.
+ * @example
+ * isUndefined(undefined); // true
+ * isUndefined(null); // false
+ * isUndefined(0); // false
+ */
+export declare const isUndefined: (value: unknown) => value is undefined;
+/**
+ * Nullish check (null or undefined).
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is null | undefined } True iff `value` is null or undefined.
+ * @example
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(0); // false
+ * isNil(''); // false
+ */
+export declare const isNil: (value: unknown) => value is null | undefined;
+/**
+ * Primitive string check.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is string } True iff `typeof value === 'string'`.
+ * @example
+ * isString('hello'); // true
+ * isString(''); // true
+ * isString(42); // false
+ * isString(new String('hello')); // false (boxed String, not primitive)
+ */
+export declare const isString: (value: unknown) => value is string;
+/**
+ * Narrowing return type for `isEmpty`. Listed unions are the structural
+ * "empty" shapes; the negation `!isEmpty(x)` strips `null | undefined`
+ * (and the empty literal forms where TS retains discrimination), so a
+ * `string | undefined` source narrows to `string` after a non-empty check.
+ */
+type EmptyValue = null | undefined | '' | readonly never[] | Map<unknown, never> | Set<never> | Record<string, never>;
+/**
+ * Empty-shape check (nullish, empty string, array, Map, Set, or plain object). Numbers and booleans are never empty.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is EmptyValue } True iff `value` is an empty shape.
+ * @example
+ * isEmpty(null); // true
+ * isEmpty(undefined); // true
+ * isEmpty(''); // true
+ * isEmpty([]); // true
+ * isEmpty({}); // true
+ * isEmpty(new Map()); // true
+ * isEmpty(new Set()); // true
+ * isEmpty('hello'); // false
+ * isEmpty(0); // false
+ * isEmpty(false); // false
+ * isEmpty([0]); // false
+ * isEmpty({ a: undefined }); // false (key still counted)
+ */
+export declare const isEmpty: (value: unknown) => value is EmptyValue;
+/**
+ * Callable check. Narrowing preserves the callable member of a union so the
+ * value stays invocable with its original signature.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is (...args: never[]) => unknown } True iff `typeof value === 'function'`.
+ * @example
+ * isFunction(() => 1); // true
+ * isFunction(class {}); // true (classes are callable)
+ * isFunction(42); // false
+ */
+export declare const isFunction: (value: unknown) => value is (...args: never[]) => unknown;
+export {};
+//# sourceMappingURL=type-guards.d.ts.map

package/dist/type-guards.js

@@ -0,0 +1,102 @@
+/**
+ * Narrowing type guards, duplicated per package by design (see CLAUDE.md) —
+ * mirrored from the identity service's canonical `utils/type-guards.ts`, plus
+ * a package-local `isFunction` (the canonical set has no function guard).
+ */
+/**
+ * Strict null check.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is null } True iff `value === null`.
+ * @example
+ * isNull(null); // true
+ * isNull(undefined); // false
+ * isNull(0); // false
+ * isNull(''); // false
+ */
+export const isNull = (value) => value === null;
+/**
+ * Strict undefined check.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is undefined } True iff `value === undefined`.
+ * @example
+ * isUndefined(undefined); // true
+ * isUndefined(null); // false
+ * isUndefined(0); // false
+ */
+export const isUndefined = (value) => value === undefined;
+/**
+ * Nullish check (null or undefined).
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is null | undefined } True iff `value` is null or undefined.
+ * @example
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(0); // false
+ * isNil(''); // false
+ */
+export const isNil = (value) => isNull(value) || isUndefined(value);
+/**
+ * Primitive string check.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is string } True iff `typeof value === 'string'`.
+ * @example
+ * isString('hello'); // true
+ * isString(''); // true
+ * isString(42); // false
+ * isString(new String('hello')); // false (boxed String, not primitive)
+ */
+export const isString = (value) => typeof value === 'string';
+/**
+ * Empty-shape check (nullish, empty string, array, Map, Set, or plain object). Numbers and booleans are never empty.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is EmptyValue } True iff `value` is an empty shape.
+ * @example
+ * isEmpty(null); // true
+ * isEmpty(undefined); // true
+ * isEmpty(''); // true
+ * isEmpty([]); // true
+ * isEmpty({}); // true
+ * isEmpty(new Map()); // true
+ * isEmpty(new Set()); // true
+ * isEmpty('hello'); // false
+ * isEmpty(0); // false
+ * isEmpty(false); // false
+ * isEmpty([0]); // false
+ * isEmpty({ a: undefined }); // false (key still counted)
+ */
+export const isEmpty = (value) => {
+    if (isNil(value)) {
+        return true;
+    }
+    if (isString(value)) {
+        return value.length === 0;
+    }
+    if (Array.isArray(value)) {
+        return value.length === 0;
+    }
+    if (value instanceof Map || value instanceof Set) {
+        return value.size === 0;
+    }
+    if (typeof value === 'object') {
+        return Object.keys(value).length === 0;
+    }
+    return false;
+};
+/**
+ * Callable check. Narrowing preserves the callable member of a union so the
+ * value stays invocable with its original signature.
+ *
+ * @param { unknown } value Value to test.
+ * @returns { value is (...args: never[]) => unknown } True iff `typeof value === 'function'`.
+ * @example
+ * isFunction(() => 1); // true
+ * isFunction(class {}); // true (classes are callable)
+ * isFunction(42); // false
+ */
+export const isFunction = (value) => typeof value === 'function';
+//# sourceMappingURL=type-guards.js.map