@authhero/adapter-interfaces 3.9.0 → 3.11.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/types/auth0/Totals.d.ts

@@ -4,10 +4,17 @@ export declare const totalsSchema: z.ZodObject<{
     limit: z.ZodNumber;
     length: z.ZodNumber;
     total: z.ZodOptional<z.ZodNumber>;
+    next: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export interface Totals {
     start: number;
     limit: number;
     length: number;
     total?: number;
+    /**
+     * Opaque keyset cursor for the next page. Set only when the caller paginated
+     * with from/take and more rows may follow; absent on the last page and for
+     * offset (page/per_page) pagination.
+     */
+    next?: string;
 }

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

@@ -0,0 +1,22 @@
+/**
+ * URL-safe base64 ("base64url", RFC 4648 §5) without padding.
+ *
+ * This is the canonical base64url implementation for the AuthHero packages.
+ * It lives in `adapter-interfaces` (the lowest package) so every other package
+ * can depend on it, replacing scattered hand-rolled `btoa/atob` variants and
+ * the `oslo/encoding` dependency we are migrating away from.
+ *
+ * Both byte- and string-oriented helpers are provided:
+ *  - `encodeBase64Url` / `decodeBase64Url` work on raw bytes (`Uint8Array`),
+ *    matching how most callers use it (hashes, random bytes, JWT segments).
+ *  - `encodeBase64UrlString` / `decodeBase64UrlString` wrap those with UTF-8
+ *    (de)coding for the common "encode a JSON/text payload" case.
+ */
+/** Encode raw bytes as a padding-free base64url string. */
+export declare function encodeBase64Url(bytes: Uint8Array): string;
+/** Decode a base64url string (with or without padding) back to raw bytes. */
+export declare function decodeBase64Url(input: string): Uint8Array;
+/** Encode a UTF-8 string as a padding-free base64url string. */
+export declare function encodeBase64UrlString(input: string): string;
+/** Decode a base64url string produced from UTF-8 text back to that string. */
+export declare function decodeBase64UrlString(input: string): string;

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

@@ -0,0 +1,27 @@
+export interface CursorPayload {
+    /**
+     * Value of the sort column on the last row of the previous page. `null` when
+     * that column was null on the boundary row. Absent for id-only ordering.
+     */
+    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
+ * as `next` and accepting back as `from`.
+ */
+export declare function encodeCursor(payload: CursorPayload): string;
+/**
+ * Decode an opaque cursor token. Returns `null` for malformed or unparseable
+ * tokens so callers can fall back gracefully (e.g. start from the beginning)
+ * instead of throwing on client-supplied input.
+ */
+export declare function decodeCursor(token: string): CursorPayload | null;

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

@@ -2,3 +2,6 @@ export * from "./user-id";
 export * from "./passthrough";
 export * from "./connection-attributes";
 export * from "./guards";
+export * from "./base64url";
+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.9.0",
+  "version": "3.11.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": {