@authhero/adapter-interfaces 3.10.0 → 3.12.0

package/dist/types/sql/dates.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Date conversion utilities shared by the SQL adapters (kysely, drizzle).
+ *
+ * Databases may hold timestamps in either of two formats during migration:
+ * - Old format: varchar(35) ISO 8601 strings (e.g., "2024-01-15T10:30:00.000Z")
+ * - New format: bigint Unix timestamps in milliseconds (e.g., 1705315800000),
+ *   stored in `_ts`-suffixed columns
+ *
+ * The adapter interface always uses ISO strings, so adapters convert:
+ * - On READ: detect the stored format and convert to an ISO string
+ * - On WRITE: write as bigint timestamp (new format)
+ *
+ * This allows zero-downtime migration where:
+ * 1. Deploy code that reads both formats, writes new format
+ * 2. Run migration to convert existing data
+ * 3. (Optional) Remove old format support after migration completes
+ */
+/**
+ * Type for a date field that could be either format from the database
+ */
+export type DbDateField = string | number | null | undefined;
+/**
+ * Convert a database date field (either format) to an ISO string for the
+ * adapter interface. Returns undefined if the value is null/undefined/empty.
+ */
+export declare function dbDateToIso(value: DbDateField): string | undefined;
+/**
+ * Convert a database date field to ISO string, with a required fallback.
+ * Use this for non-nullable date fields like created_at.
+ */
+export declare function dbDateToIsoRequired(value: DbDateField, fallback?: string): string;
+/**
+ * Convert an ISO string from the adapter interface to a bigint timestamp
+ * for writing to the database.
+ */
+export declare function isoToDbDate(isoString: string | null | undefined): number | null;
+/**
+ * Get current timestamp as ISO string (for adapter interface)
+ */
+export declare function nowIso(): string;
+/**
+ * Convert date fields from DB format to adapter format (ISO strings).
+ * Strips the _ts suffix from column names (e.g., created_at_ts -> created_at).
+ * @param row - The database row object
+ * @param requiredColumns - Columns that must have a value (will use fallback if null)
+ * @param optionalColumns - Columns that can be undefined
+ * @returns Object with converted date fields (with _ts suffix stripped)
+ */
+export declare function convertDatesToAdapter<T extends Record<string, DbDateField>, R extends Extract<keyof T, string>, O extends Extract<keyof T, string> = never>(row: T, requiredColumns: R[], optionalColumns?: O[]): Record<string, string | undefined>;

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

@@ -0,0 +1,7 @@
+/**
+ * Helpers shared by the SQL adapters (kysely, drizzle), published as the
+ * `@authhero/adapter-interfaces/sql` subpath so they stay out of the main
+ * adapter-contract surface: non-SQL adapters (e.g. DynamoDB) never see them.
+ */
+export * from "./dates";
+export * from "./transform";

package/dist/types/sql/transform.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Row/entity transformation helpers shared by the SQL adapters (kysely,
+ * drizzle). They convert between the adapter interface's rich entity shapes
+ * (nested objects, booleans, optional fields) and the flat SQL row shapes
+ * (JSON strings, 0/1 integers, no undefined values).
+ */
+/**
+ * Stringify a value to JSON if it's defined, otherwise return undefined.
+ * This is useful for converting objects to JSON strings for database storage.
+ */
+export declare function stringifyIfDefined<T>(value: T | undefined): string | undefined;
+/**
+ * Stringify multiple properties of an object to JSON strings.
+ * Only properties that are defined will be stringified.
+ *
+ * @param obj - The source object containing properties to stringify
+ * @param properties - Array of property names to stringify
+ * @param target - The target object to write stringified values to (defaults to a new object based on obj)
+ * @returns The target object with stringified properties
+ *
+ * @example
+ * const source = { flags: { enabled: true }, sessions: { timeout: 300 }, name: "Test" };
+ * const result = stringifyProperties(source, ['flags', 'sessions']);
+ * // result = { flags: '{"enabled":true}', sessions: '{"timeout":300}', name: "Test" }
+ */
+type StringifiedProperties<T, K extends keyof T> = {
+    [P in keyof T]: P extends K ? undefined extends T[P] ? string | undefined : string : T[P];
+};
+export declare function stringifyProperties<T extends Record<string, unknown>, K extends keyof T & string>(obj: T, properties: K[]): StringifiedProperties<T, K>;
+export declare function stringifyProperties<T extends Record<string, unknown>, U extends Record<string, unknown>>(obj: T, properties: (keyof T & string)[], target: U): U;
+/**
+ * Convert boolean properties to integers (1 for true, 0 for false).
+ * Only properties that are defined will be converted.
+ *
+ * @param source - The source object containing boolean properties to convert
+ * @param properties - Array of property names to convert
+ * @param target - The target object to write integer values to (defaults to source)
+ *
+ * @example
+ * const source = { enabled: true, active: false, name: "Test" };
+ * const result = {};
+ * booleanToInt(source, ['enabled', 'active'], result);
+ * // result = { enabled: 1, active: 0 }
+ */
+export declare function booleanToInt<T extends Record<string, unknown>>(source: Partial<T>, properties: (keyof T & string)[], target?: Record<string, unknown>): void;
+/**
+ * Remove undefined and null properties from an object.
+ * This keeps the SQL payload clean by only including defined values.
+ */
+export declare function removeUndefinedAndNull<T extends Record<string, unknown>>(obj: T): Partial<T>;
+/**
+ * Remove null properties from an object recursively. Used when mapping SQL
+ * rows (where missing values are NULL) back to adapter entities (where they
+ * are absent).
+ */
+export declare function removeNullProperties<T>(obj: unknown): T;
+/**
+ * Get a COUNT(*) result as an integer regardless of how the DB driver
+ * returns it (string, number, or bigint).
+ */
+export declare function getCountAsInt(count: string | number | bigint): number;
+export {};

package/dist/types/utils/base32.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Base32 (RFC 4648 §6, uppercase alphabet), the canonical implementation
+ * for the AuthHero packages. Replaces the `oslo/encoding` dependency we
+ * are migrating away from.
+ *
+ * The primary consumer is TOTP secret handling (RFC 6238 secrets are
+ * conventionally shared as unpadded base32). Encoding is padding-free;
+ * decoding is lenient and accepts input with or without padding.
+ */
+/** Encode raw bytes as a padding-free base32 string. */
+export declare function encodeBase32(bytes: Uint8Array): string;
+/** Decode a base32 string (with or without padding, case-insensitive)
+ * back to raw bytes. Throws on non-canonical input: characters outside
+ * the alphabet, impossible unpadded lengths, or non-zero trailing bits —
+ * so distinct malformed strings can never normalize to the same bytes. */
+export declare function decodeBase32(input: string): Uint8Array;

package/dist/types/utils/base64.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Standard base64 (RFC 4648 §4), the canonical implementation for the
+ * AuthHero packages (see base64url.ts for the URL-safe variant). Replaces
+ * the `oslo/encoding` dependency we are migrating away from.
+ *
+ * Encoding emits padding ("=") to match the conventional wire format
+ * (PEM bodies, `openssl rand -base64` keys). Decoding is lenient and
+ * accepts input with or without padding.
+ */
+/** Encode raw bytes as a padded standard-base64 string. */
+export declare function encodeBase64(bytes: Uint8Array): string;
+/** Decode a standard-base64 string (with or without padding) to raw bytes. */
+export declare function decodeBase64(input: string): Uint8Array;

package/dist/types/utils/cursor.d.ts

@@ -6,6 +6,13 @@ export interface CursorPayload {
     s?: string | number | null;
     /** Id of the last row of the previous page — the unique tiebreaker. */
     i: string;
+    /**
+     * Sort spec the cursor was minted under (e.g. `date:desc`). Set by endpoints
+     * that honor a caller-chosen sort in checkpoint mode, so a token replayed
+     * with a different sort is rejected instead of silently returning pages from
+     * the wrong position. Absent on fixed-sort endpoints.
+     */
+    k?: string;
 }
 /**
  * Encode a keyset position into an opaque cursor token suitable for returning

package/dist/types/utils/hex.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Lowercase hex encoding, the canonical implementation for the AuthHero
+ * packages. Replaces the `oslo/encoding` dependency we are migrating
+ * away from.
+ */
+/** Encode bytes as a lowercase hex string. Accepts an ArrayBuffer so
+ * Web Crypto digest/thumbprint results can be passed directly. */
+export declare function encodeHex(data: Uint8Array | ArrayBuffer): string;

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

@@ -3,4 +3,8 @@ export * from "./passthrough";
 export * from "./connection-attributes";
 export * from "./guards";
 export * from "./base64url";
+export * from "./base64";
+export * from "./base32";
+export * from "./hex";
 export * from "./cursor";
+export * from "./lucene";

package/dist/types/utils/lucene.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared pieces of the Lucene-style `q` filter handling. The SQL generation
+ * itself is ORM-specific and lives in each adapter; what is shared here is
+ * the query-string sanitization that enforces the tenant boundary.
+ */
+export declare function sanitizeLuceneQuery(query: string, allowedFields: string[]): string;

package/package.json

@@ -11,7 +11,7 @@
     "type": "git",
     "url": "https://github.com/markusahlstrand/authhero"
   },
-  "version": "3.10.0",
+  "version": "3.12.0",
   "files": [
     "dist"
   ],
@@ -20,9 +20,14 @@
   "types": "dist/adapter-interfaces.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/adapter-interfaces.d.ts",
       "require": "./dist/adapter-interfaces.cjs",
-      "import": "./dist/adapter-interfaces.mjs",
-      "types": "./dist/adapter-interfaces.d.ts"
+      "import": "./dist/adapter-interfaces.mjs"
+    },
+    "./sql": {
+      "types": "./dist/sql.d.ts",
+      "require": "./dist/sql.cjs",
+      "import": "./dist/sql.mjs"
     }
   },
   "devDependencies": {