@authhero/adapter-interfaces 4.5.0 → 4.6.0

package/dist/types/adapters/Analytics.d.ts

@@ -1,4 +1,4 @@
-import { AnalyticsQueryParams, AnalyticsQueryResponse, AnalyticsResource } from "../types/Analytics";
+import { AnalyticsQueryParams, AnalyticsQueryResponse, AnalyticsResource, SessionRetentionParams, SessionRetentionResponse } from "../types/Analytics";
 export interface AnalyticsAdapter {
     /**
      * Run an analytics query for a tenant. The adapter is responsible for
@@ -6,4 +6,11 @@ export interface AnalyticsAdapter {
      * tenant value from a client-controlled source.
      */
     query(tenantId: string, resource: AnalyticsResource, params: AnalyticsQueryParams): Promise<AnalyticsQueryResponse>;
+    /**
+     * Weekly session cohort retention, computed from the sessions table
+     * (created_at_ts × used_at_ts) rather than logs. Optional: adapters that
+     * only see log events (e.g. Analytics Engine) cannot implement it, and the
+     * route responds 501 when it is absent.
+     */
+    sessionRetention?(tenantId: string, params: SessionRetentionParams): Promise<SessionRetentionResponse>;
 }

package/dist/types/types/Analytics.d.ts

@@ -72,6 +72,45 @@ export interface AnalyticsQueryResponse {
         bytes_read?: number;
     };
 }
+export interface SessionRetentionParams {
+    /** Number of weekly cohorts to include, counting back from the current week */
+    weeks: number;
+}
+export interface SessionRetentionCohort {
+    /** ISO date (UTC Monday) the cohort week starts on */
+    cohort: string;
+    /** Sessions created during the cohort week */
+    sessions: number;
+    /**
+     * active[k] = sessions still active k weeks after the cohort week, i.e.
+     * last used during week k or later. active[0] === sessions. The array is
+     * truncated at the current week, so recent cohorts have fewer entries.
+     */
+    active: number[];
+}
+export interface SessionRetentionResponse {
+    interval: "week";
+    /** Inclusive lower bound of the first cohort week */
+    from: string;
+    /** Timestamp the query ran at; the last cohort week is still in progress */
+    to: string;
+    cohorts: SessionRetentionCohort[];
+}
+export declare const sessionRetentionCohortSchema: z.ZodObject<{
+    cohort: z.ZodString;
+    sessions: z.ZodNumber;
+    active: z.ZodArray<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const sessionRetentionResponseSchema: z.ZodObject<{
+    interval: z.ZodLiteral<"week">;
+    from: z.ZodString;
+    to: z.ZodString;
+    cohorts: z.ZodArray<z.ZodObject<{
+        cohort: z.ZodString;
+        sessions: z.ZodNumber;
+        active: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const analyticsColumnMetaSchema: z.ZodObject<{
     name: z.ZodString;
     type: z.ZodString;

package/dist/types/types/Hook.d.ts

@@ -1,4 +1,14 @@
 import { z } from "@hono/zod-openapi";
+/**
+ * Built-in universal-login pages a page hook can interrupt the login with.
+ * The runtime redirects to `/u/{page_id}` (or `/u2/{page_id}`), so this enum
+ * is the allowlist of interstitial screens — a free-form string would let a
+ * misconfigured hook bounce logins to an arbitrary universal-login path.
+ */
+export declare const hookPageId: z.ZodEnum<{
+    impersonate: "impersonate";
+}>;
+export type HookPageId = z.infer<typeof hookPageId>;
 export declare const hookTemplateId: z.ZodEnum<{
     "ensure-username": "ensure-username";
     "set-preferred-username": "set-preferred-username";
@@ -77,6 +87,19 @@ export declare const hookInsertSchema: z.ZodUnion<readonly [z.ZodObject<{
     priority: z.ZodOptional<z.ZodNumber>;
     hook_id: z.ZodOptional<z.ZodString>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    trigger_id: z.ZodEnum<{
+        "post-user-login": "post-user-login";
+    }>;
+    page_id: z.ZodEnum<{
+        impersonate: "impersonate";
+    }>;
+    permission_required: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    synchronous: z.ZodDefault<z.ZodBoolean>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    hook_id: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>]>;
 export type HookInsert = z.infer<typeof hookInsertSchema>;
 export declare const hookSchema: z.ZodUnion<readonly [z.ZodObject<{
@@ -148,5 +171,20 @@ export declare const hookSchema: z.ZodUnion<readonly [z.ZodObject<{
     updated_at: z.ZodString;
     hook_id: z.ZodString;
     code_id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    trigger_id: z.ZodEnum<{
+        "post-user-login": "post-user-login";
+    }>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    synchronous: z.ZodDefault<z.ZodBoolean>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    hook_id: z.ZodString;
+    page_id: z.ZodEnum<{
+        impersonate: "impersonate";
+    }>;
+    permission_required: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>]>;
 export type Hook = z.infer<typeof hookSchema>;

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

@@ -8,3 +8,4 @@ export * from "./base32";
 export * from "./hex";
 export * from "./cursor";
 export * from "./lucene";
+export * from "./session-retention";

package/dist/types/utils/session-retention.d.ts

@@ -0,0 +1,32 @@
+import { SessionRetentionResponse } from "../types/Analytics";
+export declare const WEEK_MS: number;
+/**
+ * The Unix epoch (1970-01-01) was a Thursday; adding 3 days before dividing
+ * by a week aligns bucket boundaries to Monday 00:00 UTC.
+ */
+export declare const MONDAY_EPOCH_SHIFT_MS: number;
+/** Monday-aligned week index for an epoch-ms timestamp. */
+export declare function weekIndex(epochMs: number): number;
+/** Epoch ms of the UTC Monday a week index starts on. */
+export declare function weekStartMs(week: number): number;
+export interface SessionRetentionWindow {
+    currentWeek: number;
+    firstWeek: number;
+    /** Epoch ms lower bound for created_at_ts — the start of the first cohort week */
+    sinceMs: number;
+}
+export declare function sessionRetentionWindow(weeks: number, now?: number): SessionRetentionWindow;
+export interface SessionRetentionRawRow {
+    /** Monday-aligned week index the session was created in */
+    created_week: number;
+    /** Monday-aligned week index the session was last used in */
+    used_week: number;
+    count: number;
+}
+/**
+ * Fold raw (created-week × last-used-week) counts into per-cohort retention.
+ * A session counts as active k weeks after its cohort week when it was last
+ * used during that week or any later one, so a single last-used timestamp is
+ * enough to reconstruct the whole retention triangle.
+ */
+export declare function buildSessionRetention(rows: SessionRetentionRawRow[], weeks: number, now?: number): SessionRetentionResponse;

package/package.json

@@ -11,7 +11,7 @@
     "type": "git",
     "url": "https://github.com/markusahlstrand/authhero"
   },
-  "version": "4.5.0",
+  "version": "4.6.0",
   "files": [
     "dist"
   ],